ScalePad MCP 2.0

Connect your AI client to ScalePad with OAuth, discover product tools, and start with a read-only request.

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. The selected account's product subscriptions affect discovery. The underlying APIs enforce the signed-in user's permissions for individual requests.

Use this connection information:

SettingValue
Server URLhttps://mcp.scalepad.com/mcp
TransportStreamable HTTP
AuthenticationOAuth through ScalePad sign-in
Required scopemcp:tools
Expected token audience (discovered by Codex)https://mcp.scalepad.com/mcp

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.

Leave the OAuth resource/audience unset. Codex discovers the resource from ScalePad’s OAuth metadata. If you already set oauth_resource for this server, remove it before retrying sign-in.

Run:

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

Complete ScalePad sign-in in the browser. Start a new Codex session to load the tools. See the official OpenAI MCP documentation.

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

Use direct tools such as scalepad_query_clients for common reads and summaries. For other operations, call search_operations with keywords or an exact operation ID. Each match includes an operation_id, an execution_tool, the input schema, and example arguments. Follow next_offset when more matches are available.

See the MCP tool reference for the advertised tools. An authenticated tools/list response gives the current names, input schemas, and annotations for your connection. The selected account's subscriptions and the user's permissions affect what you can discover and call.

Read and write behavior

Use a direct read tool or execute_read for analysis. The execute_write tool changes ScalePad data after validation and authorization succeed. Use your MCP client's approval controls and review the target record and proposed changes before approving a write. The mcp:tools scope covers both reads and writes.

If a write times out or its outcome is uncertain, check the affected record before submitting it again.

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"}}}'

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 scalepad_query_clients advertises get_client_summary, use a client ID you retrieved and request a single section:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "scalepad_query_clients",
    "arguments": {
      "operation": "get_client_summary",
      "client_id": "11111111-1111-4111-8111-111111111111",
      "sections": ["open_tasks"]
    }
  }
}

To use operation discovery, send a tools/call with name set to search_operations and arguments set to a query such as {"query":"query_compliance_health.get_client_health"}. If the result includes that operation, the read call uses the returned executor and operation ID:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "execute_read",
    "arguments": {
      "operation_id": "query_compliance_health.get_client_health",
      "arguments_json": "{\"client_id\":\"11111111-1111-4111-8111-111111111111\"}"
    }
  }
}

Use a real ControlMap client ID for this example. For a write, follow the same discovery flow and use execute_write when returned, after reviewing and approving the change. arguments_json is a string containing a JSON object that matches the discovered operation schema. For direct tools, follow the schema from tools/list, including any individual fields that accept JSON as text.

Check the JSON-RPC error and tool result isError before using structuredContent. Read the selected operation's pagination and coverage fields before interpreting a response as complete.

Refresh your tool catalog

  1. Use your client's tool or connector refresh command. If it has none, reconnect the ScalePad MCP server and start a new session. If the selected account or its product subscriptions changed, renew ScalePad sign-in as needed.
  2. Check the refreshed tool names against a fresh authenticated tools/list for the same account. If the server returns the new catalog but the client still shows the old one, the client needs to refresh its saved import.
  3. Open saved workflows that reference old names or argument schemas. Rebind or re-import the affected tools and run a read-only check. Follow the changelog for migration examples.

On the 2025-06-18 and 2025-11-25 protocol revisions, clients that resume the authenticated GET event stream with Last-Event-ID can receive notifications/tools/list_changed. Custom clients should fetch tools/list again when they receive it. On 2026-07-28, refresh discovery explicitly. Refreshing discovery and updating a saved workflow are separate actions.

Protocol behavior

The endpoint uses stateless Streamable HTTP and issues no MCP session ID. Send one JSON-RPC object per POST request. The request body limit is 1 MiB. Use the protocol version negotiated with the server.

Troubleshooting

SymptomWhat to check
401 UnauthorizedComplete OAuth sign-in again. Check token expiry, the exact MCP audience, mcp:tools, and whether authentication resolves a ScalePad account and user. A missing required scope also returns 401.
Microsoft 365 Copilot connects but tool calls return 401Check that the Teams Developer Portal authorization endpoint includes audience=https%3A%2F%2Fmcp.scalepad.com%2Fmcp, then disconnect and connect again in Copilot Chat.
OAuth registration fails, unauthorized_client, or callback mismatchCheck the client's OAuth registration method, allowed redirect URI, and grant configuration. Discovery metadata alone does not prove a particular client can sign in.
Codex shows “Something went wrong” during ScalePad sign-inAn explicit resource can make Codex send the same OAuth resource twice. Remove oauth_resource = "https://mcp.scalepad.com/mcp" from [mcp_servers.scalepad-products] in ~/.codex/config.toml. Keep the server URL and retry with codex mcp login scalepad-products --scopes mcp:tools. In Codex Desktop, restart after saving the configuration and select Authenticate again.
Expected tool or operation is missingConfirm the selected account and its product subscriptions, then refresh discovery. Use search_operations for operations outside the advertised direct tools.
Unknown tool or operationRefresh tools/list, then rebind saved workflows to the current names and schemas.
validation_error or JSON-RPC -32602Check the direct tool's input schema or the operation schema returned by search_operations. For executors, pass the operation inputs as a JSON object encoded in arguments_json.
HTTP succeeds but the task failsCheck both the top-level JSON-RPC error and tool result isError. HTTP 200 alone does not establish successful tool execution.
public_api_errorInspect the result's status_code and message. The underlying API can reject permissions or missing records, apply validation, or rate limit requests. Correct validation errors before retrying.
HTTP 404 or method errorCheck the exact server hostname and /mcp path, and use HTTP POST for protocol requests.
File upload or download is unavailableBinary, multipart, and signed-file workflows are excluded from the product MCP catalog. Use the appropriate product API or UI for those workflows.

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


Did this page help you?