Custom MCP clients

Metatate Cloud's endpoint is standard MCP over HTTP with bearer authentication — there is no proprietary protocol and no client SDK requirement. Any MCP client that supports the HTTP transport with custom headers can connect. Requests are single POST calls to /mcp in the transport's stateless mode: there is no session to maintain and no standalone event stream to subscribe to.

Configuration

Most MCP clients accept a server entry of this shape:

{
  "type": "http",
  "url": "<mcp-server-url>/mcp",
  "headers": {
    "Authorization": "Bearer <your-access-token>"
  }
}

Some clients nest the same values differently (for example Cursor's mcpServers map, which drops the type field) — the Connect tab of your workspace's MCP module renders ready-to-paste snippets for Claude Code, Cursor, and curl with your real endpoint filled in.

You need two values:

• Endpoint URL — shown on the Connect tab of your workspace's MCP module. The same endpoint serves every workspace; your token selects yours, so clients never send a workspace name or ID.
• Access token — issued on the Tokens tab (workspace admin or owner role). It looks like mtt_ followed by 64 hex characters, is shown exactly once at issue, and can be revoked at any time. See Connect an agent for token handling.

Verify the connection

The health route needs no token and separates URL problems from auth problems:

curl -sS https://<workspace-mcp-host>/health

Then verify auth end to end with a tools/list:

curl -sS <mcp-server-url>/mcp \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A tools/list that returns the seven tools means your client config will work. Any invalid token returns an identical unauthorized response — see Troubleshooting if you get a 401.

Tool name aliases

tools/list advertises the canonical snake_case names (discover_context, authorize_use, …). For clients that normalize tool names, tools/call also accepts hyphenated aliases 1:1 (discover-context for discover_context); the underscore names remain canonical. See the MCP server overview for the tool inventory.

What is validated, honestly

Claude Code is the packaged, documented integration (Claude Code plugin). Other named clients are not individually validated by Metatate — but the endpoint deliberately exposes nothing beyond standard MCP over HTTP with a bearer header, so if your client speaks that, it should work.

If a client misbehaves, establish a baseline first: run the same tool with the same input from the workbench on your workspace's MCP page — its live-endpoint mode sends a real tools/call to the deployed endpoint with your token, the exact path your client takes. If the workbench call succeeds and your client's does not, the difference is in your client's transport or headers, not your governance state. See MCP tools in the app.