MCP server

Openhandle runs a remote MCP server over Streamable HTTP. Every public API endpoint is one tool. The tool names, inputs, and responses match the REST API.

https://api.openhandle.dev/mcp

Connect a client

Add the URL to your MCP client. The client discovers the OAuth settings, opens Openhandle in your browser, and asks you to approve the connection. You pick the workspace environment on that screen:

• Test answers every tool with synthetic data at $0.000 actual charge.
• Live uses real public data and normal billing. Live needs a verified workspace owner email.

Openhandle creates one API key for the connection. The key is named after the client, for example Claude (MCP). Usage, request history, and spend caps work the same as for any other key.

Disconnect a client under Settings → MCP server in the dashboard. That revokes the key and every token at once.

OAuth details

The server follows the MCP authorization specification.

• Grant types: authorization_code with PKCE (S256), and refresh_token.
• Scopes: read:instagram, read:tiktok, and read:twitter.
• Legacy scope: mcp grants all MCP tools and remains the default when scope is omitted.
• Public clients register with token_endpoint_auth_method: none. Confidential clients receive a client secret.
• Access tokens live for one hour. Refresh tokens rotate on every use and live for 30 days.
• Send resource=https://api.openhandle.dev/mcp when your client supports resource indicators.

Browser authorization flow

The authorization endpoint validates the OAuth parameters and stores a short-lived authorization request. It then redirects the browser to the dashboard consent page with an opaque request identifier. The dashboard loads the stored request from the API and shows the client, requested access, environment, and spend-cap options.

Production sessions use a cookie shared across the api.openhandle.dev and app.openhandle.dev subdomains. An unauthenticated user signs in through the dashboard and then returns to the same consent request. Approval sends the browser to the client's registered redirect URI with the authorization code and original state.

API key instead of OAuth

Scripts and CI jobs can skip the browser flow. Send an API key as the bearer token:

Authorization: Bearer $OPENHANDLE_TEST_KEY

The key prefix selects the environment. There is no environment argument, header, or setting.

Tools

• find_test_data and get_test_data find stable synthetic inputs. They are unmetered.
• Endpoint tools such as instagram_get_profile call the public API. They are metered exactly like REST calls and appear in request history with channel mcp.
• Every result carries metadata: environment, requestId, actualCharge, liveEquivalentPrice, and datasetVersion.

Read Test with MCP for the agent sequence in the test environment.

Machine-readable discovery and permissions

Use https://api.openhandle.dev/mcp as the server endpoint. The MCP setup guide explains how to connect each client.

Protected resource metadata publishes mcp, read:instagram, read:tiktok, and read:twitter in scopes_supported. Request only the platforms your agent needs, for example scope=read:instagram. Combine scopes with spaces to allow multiple platforms. The consent page shows these permissions before approval. Each endpoint tool also declares its requiredScope in _meta.

Discovery tools and synthetic catalog resources remain available to every connection. No scope grants dashboard administration or social account writes. API keys retain access to all tools. Use OAuth for platform restrictions.

A call outside the token's permissions returns HTTP 403 before metering. Its WWW-Authenticate challenge declares error="insufficient_scope", the required scope, and the protected resource metadata URL. Authorize the additional scope in the browser before retrying.

Refresh requests can narrow access-token permissions. Rotated refresh tokens retain their original permissions, as required by OAuth. Reauthorizing a connection never expands permissions on an existing token.

The Openhandle MCP manifest uses the official MCP Registry server.json format and declares the actual Streamable HTTP endpoint. GET /mcp returns this JSON description without special request headers. The same manifest remains available at /mcp.json. JSON-RPC POST requests to the website URL redirect to the API endpoint; configure the API URL directly to avoid redirects.

An unauthenticated request returns HTTP 401 and a WWW-Authenticate header pointing to the protected resource metadata. This is expected. Verify a server with an authenticated JSON-RPC initialize request using Streamable HTTP, not by expecting a public JSON document from an unauthenticated website GET.