ScalePad MCP 2.0

Connect your AI assistant or editor to ScalePad to retrieve product data and perform supported actions using the Model Context Protocol (MCP). The product MCP server exposes tools backed by ScalePad APIs and runs requests as the signed-in ScalePad user.

Before you connect

You need a ScalePad user account and an AI client that supports remote MCP servers over Streamable HTTP with OAuth authentication. Product-specific workflows depend on the user's product access. The underlying APIs enforce permissions for individual requests.

Use this connection information:

The mcp:tools scope allows access to the MCP endpoint. It does not grant additional product permissions or restrict a connection to read-only operations.

Connect your AI client

Add the server URL, complete the client's OAuth sign-in flow, and enable the tools you want to use. You do not need to run the ScalePad server locally or configure an LLM API key for it.

The examples below show client configuration formats. OAuth registration and callback support must also work for your client. If sign-in fails, see Troubleshooting.

codex mcp add scalepad-products --url https://mcp.scalepad.com/mcp
codex mcp login scalepad-products --scopes mcp:tools

claude mcp add --transport http scalepad-products https://mcp.scalepad.com/mcp

{
  "mcpServers": {
    "scalepad-products": {
      "url": "https://mcp.scalepad.com/mcp"
    }
  }
}

{
  "servers": {
    "scalepad-products": {
      "type": "http",
      "url": "https://mcp.scalepad.com/mcp"
    }
  }
}

Try your first request

Start with a small read-only task:

Use ScalePad to list up to five clients. Show their names and IDs, and tell me if more results are available. Do not make any changes.

Your client discovers the tools available to your user and selects the appropriate workflow. Depending on your product access, you can also try:

• "Find the client named Contoso and summarize its hardware inventory."
• "List the open tickets for this client."
• "Summarize this client's backup health."
• "Show the risks and outstanding tasks in my ControlMap account."
• "Find recent Quoter quotes for this client."

Ask the client to identify the record before requesting changes. Use IDs returned by ScalePad to avoid selecting the wrong client or record.

How tools are organized

Tools group related API operations into workflows. For example, clients.query contains client read operations, and clients.manage contains client write operations.

This table gives examples. The authenticated tools/list response is the reference for the names, operations, and schemas available to your connection.

Each generated workflow takes an operation and its arguments. Operation arguments use path, query, and body where the corresponding API requires them. For example, a client list call uses:

{
  "operation": "list_clients",
  "arguments": {
    "query": {
      "page_size": 5
    }
  }
}

The server filters product operations using the authenticated user's product access. For overlapping client, contact, agreement, and hardware operations, it prefers the Lifecycle Manager operation when the user has that access; otherwise, the corresponding Core operation can remain available. Parameters and response fields can differ between those APIs, so use the schema returned by discovery.

Read and write behavior

Generated tools separate query operations from management operations and publish MCP annotations such as readOnlyHint and destructiveHint. These hints help clients display and approve calls; they are not authorization controls.

For a connection intended only for analysis, enable query tools and keep management tools disabled in the client. The mcp:tools scope itself covers both reads and writes.

Authentication for custom clients

Fetch the protected resource metadata:

curl --fail-with-body https://mcp.scalepad.com/.well-known/oauth-protected-resource/mcp

Production advertises:

{
  "resource": "https://mcp.scalepad.com/mcp",
  "authorization_servers": ["https://auth.scalepad.com/"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp:tools"]
}

Unauthenticated MCP requests return 401 Unauthorized with a challenge identifying that document and the required scope:

WWW-Authenticate: Bearer resource_metadata="https://mcp.scalepad.com/.well-known/oauth-protected-resource/mcp", scope="mcp:tools"

Use the advertised authorization server's discovery metadata to establish OAuth endpoints and supported client registration. For interactive user connections, use authorization code with PKCE and an allowed callback URI. Acquire an access token for the exact MCP resource audience and request mcp:tools. The authorization server advertises a registration endpoint, but registration policy and support for your redirect URI determine whether registration succeeds.

Send Authorization: Bearer <access-token> on every MCP request. A token for another API audience or an ID token is not a substitute. Authentication must resolve a ScalePad account and user, so the issuer advertising a client-credentials grant does not establish support for unattended service-account MCP access.

Make a read-only request with HTTP

These examples are for developers building or diagnosing an MCP client. First obtain an MCP access token through OAuth and make it available as SCALEPAD_MCP_ACCESS_TOKEN in your shell. Do not commit tokens to configuration files or share them in logs.

Initialize the connection:

curl --fail-with-body https://mcp.scalepad.com/mcp \
  -H "Authorization: Bearer ${SCALEPAD_MCP_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"scalepad-example","version":"1.0.0"}}}'

The server supports protocol versions 2025-11-25 and 2025-06-18. Use the negotiated version returned by initialization for subsequent requests. The commands below assume it returned 2025-11-25.

Send the initialized notification, which returns HTTP 202 with no response body:

curl --fail-with-body https://mcp.scalepad.com/mcp \
  -H "Authorization: Bearer ${SCALEPAD_MCP_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

Discover tools and their input schemas:

curl --fail-with-body https://mcp.scalepad.com/mcp \
  -H "Authorization: Bearer ${SCALEPAD_MCP_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

If clients.query advertises list_clients, request a small page:

curl --fail-with-body https://mcp.scalepad.com/mcp \
  -H "Authorization: Bearer ${SCALEPAD_MCP_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"clients.query","arguments":{"operation":"list_clients","arguments":{"query":{"page_size":5}}}}}'

The two arguments objects are intentional: the outer one contains the workflow operation, and the inner one contains that operation's API parameters.

The server returns JSON-RPC results as JSON. Tool results include structuredContent, a text representation in content, and an isError flag. Successful generated API results contain source, operation, operation_id, status_code, and the API response under data. Response data follows the selected product API's contract.

For paginated operations, follow the selected API's cursor fields and pass the returned cursor in the next call's query. Request small pages and select fields when the discovered schema supports that option.

Protocol behavior

The endpoint uses stateless HTTP POST requests and does not issue an MCP session ID. It supports initialize, ping, tools/list, and tools/call. Notifications return HTTP 202 without a JSON-RPC response. It advertises tools with listChanged: false; it does not advertise resources or prompts. Reconnect or refresh discovery after changes to your product access.

Send one JSON-RPC object per request. The request body limit is 1 MiB. Use /mcp on the product server hostname; a browser GET request or an SSE subscription is not a tool call.

Troubleshooting

If a write times out or its outcome is uncertain, check the affected record before submitting it again. MCP calls do not inherit the ScalePad Assistant's confirmation-token replay protection.

To disconnect, disable or remove the server in your AI client and use its authentication controls to clear stored credentials.