{
  "schema_version": "agentpmt.docs.v1",
  "generated_at": "2026-07-17T10:35:38.347Z",
  "release_id": "29bf60dec4cba533b55ccd3d64f2f8b0eb3995cd2130786e2841eb9366a76ffc",
  "id": "generated-mcp-connection",
  "page_url": "https://www.agentpmt.com/docs/mcp-reference/connection",
  "markdown_url": "https://www.agentpmt.com/docs/mcp-reference/connection?format=agent-md",
  "json_url": "https://www.agentpmt.com/docs/mcp-reference/connection?format=agent-json",
  "source_path": "content/docs/connection.mdoc",
  "updated_at": "2026-05-27T04:40:56.000Z",
  "headings": [
    {
      "depth": 2,
      "id": "prerequisites",
      "title": "Prerequisites"
    },
    {
      "depth": 2,
      "id": "hosted-streamable-https-endpoint",
      "title": "Hosted Streamable HTTPS Endpoint"
    },
    {
      "depth": 2,
      "id": "complete-hosted-config-examples",
      "title": "Complete Hosted Config Examples"
    },
    {
      "depth": 2,
      "id": "local-stdio-fallback",
      "title": "Local STDIO Fallback"
    },
    {
      "depth": 2,
      "id": "platform-specific-local-config-examples",
      "title": "Platform-Specific Local Config Examples"
    },
    {
      "depth": 2,
      "id": "browser-based-clients",
      "title": "Browser-Based Clients"
    },
    {
      "depth": 2,
      "id": "postman-testing",
      "title": "Postman Testing"
    },
    {
      "depth": 2,
      "id": "troubleshooting",
      "title": "Troubleshooting"
    },
    {
      "depth": 2,
      "id": "discovery-and-protocol-reference",
      "title": "Discovery and Protocol Reference"
    },
    {
      "depth": 2,
      "id": "mcp-endpoint",
      "title": "MCP Endpoint"
    },
    {
      "depth": 2,
      "id": "native-mcp-methods",
      "title": "Native MCP Methods"
    },
    {
      "depth": 2,
      "id": "fetch-native-tools-and-call-them",
      "title": "Fetch Native Tools And Call Them"
    },
    {
      "depth": 3,
      "id": "1-initialize",
      "title": "1) Initialize"
    },
    {
      "depth": 3,
      "id": "2-list-current-native-tools",
      "title": "2) List current native tools"
    },
    {
      "depth": 3,
      "id": "3-call-a-tool-returned-by-toolslist",
      "title": "3) Call a tool returned by tools/list"
    },
    {
      "depth": 2,
      "id": "get-more-tools",
      "title": "Get More Tools"
    },
    {
      "depth": 3,
      "id": "1-browse-available-external-tools",
      "title": "1) Browse available external tools"
    },
    {
      "depth": 3,
      "id": "2-create-an-auth-session-for-wallet-signing",
      "title": "2) Create an auth session for wallet signing"
    },
    {
      "depth": 3,
      "id": "3-invoke-a-selected-tool",
      "title": "3) Invoke a selected tool"
    },
    {
      "depth": 2,
      "id": "well-known-discovery-urls",
      "title": "Well-Known Discovery URLs"
    },
    {
      "depth": 2,
      "id": "related-api-reference-links",
      "title": "Related API Reference Links"
    }
  ],
  "related_products": [],
  "related_workflows": [],
  "doc": {
    "title": "Connection",
    "description": "Connect MCP clients to AgentPMT with hosted Streamable HTTPS or the local STDIO fallback.",
    "category": "MCP Reference",
    "image": null,
    "full_path": "mcp-reference/connection",
    "body_markdown": "# Connection\n\nAgentPMT exposes one MCP server for your Agent Group. Use the hosted Streamable HTTPS endpoint when your client supports remote MCP. Use the local STDIO router when your client requires a command-based MCP server.\n\nThe Bearer token belongs to one Agent Group. The tools, credentials, spending caps, and activity log for that group define what the connected agent can do.\n\n## Prerequisites\n\n### Create or choose an Agent Group\n\nIn the dashboard, open **Control Center -> Agent Groups**. Add the tools and workflows this agent may use, bind required credentials, and set spend controls.\n\n### Copy the Bearer token\n\nClick **Show Bearer Token** on the group card. Treat the token like a password; it authorizes every MCP call for that group.\n\n### Choose a transport\n\nPrefer hosted Streamable HTTPS for remote-MCP clients. Choose local STDIO only when the client needs a local command.\n\n## Hosted Streamable HTTPS Endpoint\n\n```text\nEndpoint:  https://api.agentpmt.com/mcp\nTransport: Streamable HTTP over HTTPS\nAuth:      Authorization: Bearer <AGENTPMT_BEARER_TOKEN>\n```\n\nHosted MCP does not require a local package. Your client connects directly to AgentPMT over HTTPS, sends the Bearer token in config or a secret field, and receives the current tool catalog for the agent group.\n\n## Complete Hosted Config Examples\n\nUse this generic shape for MCP clients that accept remote Streamable HTTP servers in a config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://api.agentpmt.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <AGENTPMT_BEARER_TOKEN>\",\n        \"x-instance-metadata\": \"{\\\"client\\\":\\\"generic-mcp\\\",\\\"platform\\\":\\\"remote\\\"}\"\n      }\n    }\n  }\n}\n```\n\n`x-instance-metadata` is optional. When your client supports custom headers, use it to identify the client and platform in activity logs.\n\n### Cursor / Windsurf / VS Code\n\nIf your editor build exposes a remote MCP server option, use the hosted config shape above and set:\n\n```text\nURL: https://api.agentpmt.com/mcp\nAuthorization: Bearer <AGENTPMT_BEARER_TOKEN>\n```\n\nIf the editor only accepts command-based MCP servers, use the local STDIO fallback below.\n\n### ChatGPT / Claude browser clients\n\nBrowser-based clients usually store remote connector settings in the UI instead of a local file.\n\n```text\nServer URL: https://api.agentpmt.com/mcp\nAuthentication: Bearer token\nBearer token: <AGENTPMT_BEARER_TOKEN>\n```\n\nUse the client secret field for the Bearer token when one is available. Do not paste the token into public instructions, shared prompts, or browser-visible page content.\n\n### Postman MCP\n\nCreate a new MCP request in Postman and use the hosted endpoint as the request URL:\n\n```text\nURL: https://api.agentpmt.com/mcp\nHeader: Authorization: Bearer <AGENTPMT_BEARER_TOKEN>\nOptional header: x-instance-metadata: {\"client\":\"postman\",\"platform\":\"desktop\"}\n```\n\nConnect the request, inspect the loaded tools, run a simple tool call, then verify the call under **Control Center -> Agent Activity**.\n\n## Local STDIO Fallback\n\nInstall the local router when your MCP client requires a command. The router does not execute tools locally. It reads `AGENTPMT_BEARER_TOKEN`, receives JSON-RPC over STDIO, and forwards requests to `https://api.agentpmt.com/mcp`.\n\n```bash\nnpm install -g @agentpmt/mcp-router\nagentpmt-setup\n```\n\nThe setup command detects supported clients, asks for the Bearer token, and writes the appropriate config. Re-run `agentpmt-setup` when you switch agent groups or add another local client.\n\n## Platform-Specific Local Config Examples\n\nUse these blocks only for clients that need a local command. Keep `AGENTPMT_BEARER_TOKEN` in the config file or the client secret store. `X_INSTANCE_METADATA` is optional and must be a JSON string.\n\n### Claude Desktop\n\nConfig files:\n\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"claude_desktop\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nUse the command-based MCP config when your Claude Code build does not expose hosted Streamable HTTPS settings.\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"claude_code\\\",\\\"platform\\\":\\\"cli\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nConfig file: `~/.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"cursor\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\nAfter saving, open Cursor Settings -> Features -> MCP and refresh servers.\n\n### VS Code\n\nConfig files:\n\n- Windows: `%APPDATA%\\Code\\User\\mcp.json`\n- macOS: `~/Library/Application Support/Code/User/mcp.json`\n- Linux: `~/.config/Code/User/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"vscode\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nConfig file: `~/.codeium/windsurf/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"windsurf\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Zed\n\nConfig files:\n\n- Windows: `%APPDATA%\\Zed\\settings.json`\n- macOS/Linux: `~/.config/zed/settings.json`\n\n```json\n{\n  \"context_servers\": {\n    \"agentpmt\": {\n      \"settings\": {},\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n        \"env\": {\n          \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n          \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"zed\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Codex CLI\n\nConfig file: `~/.codex/config.toml`\n\n```toml\n[mcp_servers.agentpmt]\ncommand = \"npx\"\nargs = [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"]\n\n[mcp_servers.agentpmt.env]\nAGENTPMT_BEARER_TOKEN = \"<AGENTPMT_BEARER_TOKEN>\"\nX_INSTANCE_METADATA = '{\"client\":\"codex\",\"platform\":\"cli\"}'\n```\n\n### Gemini CLI\n\nConfig file: `~/.gemini/settings.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"gemini\\\",\\\"platform\\\":\\\"cli\\\"}\"\n      }\n    }\n  }\n}\n```\n\n## Browser-Based Clients\n\nUse the hosted endpoint for browser clients that support remote MCP connectors. Store the Bearer token in the connector's secret/auth field, not in a chat message.\n\nIf the browser client does not support remote MCP, use AgentPMT's direct HTTP API from your own server-side runtime instead of exposing the Bearer token in client-side code.\n\n## Postman Testing\n\nPostman is useful for verifying an agent group before you rely on an agent prompt.\n\n### Create an MCP request\n\nChoose Postman's MCP request type and set the URL to `https://api.agentpmt.com/mcp`.\n\n### Add auth and metadata\n\nAdd `Authorization: Bearer <AGENTPMT_BEARER_TOKEN>`. Optionally add `x-instance-metadata: {\"client\":\"postman\",\"platform\":\"desktop\"}`.\n\n### Connect and run a tool\n\nConnect, choose one of the loaded tools, fill in the displayed parameters, and run the request.\n\n### Verify activity\n\nOpen **Control Center -> Agent Activity** and confirm the request, response, status, and metadata are logged.\n\n## Troubleshooting\n\n| Symptom | Check |\n| --- | --- |\n| No tools appear | Confirm the Bearer token belongs to the agent group you configured and that tools are added to that group. |\n| `401` or auth failure | Re-copy the Bearer token, remove extra whitespace, and check whether the token was rotated. |\n| Client rejects hosted config | Use the local STDIO fallback; that client likely requires a command-based MCP server. |\n| Tool is listed but fails | Bind any required credentials on the Agent Group and review the tool's current schema. |\n| Activity log is missing metadata | Confirm the client supports custom headers for hosted MCP or `X_INSTANCE_METADATA` for the local router. |\n## Discovery and Protocol Reference\n\n## MCP Endpoint\n\n- https://api.agentpmt.com/mcp\n\n## Native MCP Methods\n\n- `initialize`: Negotiates MCP protocol capabilities and starts a session.\n- `notifications/initialized`: Confirms client initialization after a successful initialize call.\n- `tools/list`: Returns the currently available native tool set for the authenticated context.\n- `tools/call`: Invokes a selected native tool by name with tool-specific arguments.\n\n## Fetch Native Tools And Call Them\n\n### 1) Initialize\n\n```bash\ncurl -X POST \"https://api.agentpmt.com/mcp\" \\\n  -H \"Authorization: Bearer <oauth_access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"2025-03-26\",\n    \"clientInfo\": {\n      \"name\": \"agentpmt-docs-example-client\",\n      \"version\": \"1.0.0\"\n    },\n    \"capabilities\": {\n      \"tools\": {}\n    }\n  }\n}'\n```\n\n### 2) List current native tools\n\n```bash\ncurl -X POST \"https://api.agentpmt.com/mcp\" \\\n  -H \"Authorization: Bearer <oauth_access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/list\",\n  \"params\": {}\n}'\n```\n\n### 3) Call a tool returned by tools/list\n\n```bash\ncurl -X POST \"https://api.agentpmt.com/mcp\" \\\n  -H \"Authorization: Bearer <oauth_access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"<tool_name_from_tools_list>\",\n    \"arguments\": {\n      \"example_input\": \"value\"\n    }\n  }\n}'\n```\n\n## Get More Tools\n\n### 1) Browse available external tools\n\n```bash\ncurl -X GET \"https://www.agentpmt.com/api/external/tools?limit=20\"\n```\n\n### 2) Create an auth session for wallet signing\n\n```bash\ncurl -X POST \"https://www.agentpmt.com/api/external/auth/session\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallet_address\": \"0xYOUR_WALLET\"\n  }'\n```\n\n### 3) Invoke a selected tool\n\n```bash\ncurl -X POST \"https://www.agentpmt.com/api/external/tools/<product_slug>/actions/<action_slug>/invoke\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallet_address\": \"0xYOUR_WALLET\",\n    \"session_nonce\": \"<session_nonce>\",\n    \"request_id\": \"<unique_request_id>\",\n    \"signature\": \"0x<wallet_signature>\",\n    \"parameters\": {\n      \"example\": \"value\"\n    }\n  }'\n```\n\n## Well-Known Discovery URLs\n\n- https://www.agentpmt.com/.well-known/mcp\n- https://www.agentpmt.com/.well-known/mcp/server.json\n- https://www.agentpmt.com/.well-known/mcp/server-card.json\n- https://www.agentpmt.com/mcp.json\n- https://www.agentpmt.com/.well-known/mcp.json\n- https://www.agentpmt.com/.well-known/glama.json\n- https://api.agentpmt.com/.well-known/mcp\n- https://api.agentpmt.com/.well-known/mcp/server.json\n- https://api.agentpmt.com/.well-known/mcp/server-card.json\n- https://api.agentpmt.com/mcp.json\n- https://api.agentpmt.com/.well-known/mcp.json\n- https://api.agentpmt.com/mcp/.well-known/mcp\n- https://api.agentpmt.com/.well-known/glama.json\n\n## Related API Reference Links\n\nRaw Bearer-token API callers should use [Programmatic Access](https://www.agentpmt.com/docs/api-reference/programmatic-access). Wallet-authenticated autonomous agents should use the [Autonomous Agents API](https://www.agentpmt.com/docs/api-reference/autonomous-agents). Agents paying for one eligible tool action with direct x402 should use [X402 Payments For Tool Usage](https://www.agentpmt.com/docs/autonomous-agents/x402-payments-for-tool-usage).\n\n### [API To MCP Tool Conversion](https://www.agentpmt.com/docs/agent-connections/api-to-mcp-tool-conversion)\n\nCreate a private Connected API tool, authorize it for an Agent Group, and call it over MCP.\n"
  }
}