# Connection

> Connect MCP clients to AgentPMT with hosted Streamable HTTPS or the local STDIO fallback.

Content type: documentation
Source URL: https://www.agentpmt.com/docs/mcp-reference/connection
Markdown URL: https://www.agentpmt.com/docs/mcp-reference/connection?format=agent-md
Category: MCP Reference

---

# Connection

AgentPMT 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.

The 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.

## Prerequisites

1. **Create or choose an Agent Group**
   In the dashboard, open **Control Center -> Agent Groups**. Add the tools and workflows this agent may use, bind required credentials, and set spend controls.

2. **Copy the Bearer token**
   Click **Show Bearer Token** on the group card. Treat the token like a password; it authorizes every MCP call for that group.

3. **Choose a transport**
   Prefer hosted Streamable HTTPS for remote-MCP clients. Choose local STDIO only when the client needs a local command.

## Hosted Streamable HTTPS Endpoint

```text
Endpoint:  https://api.agentpmt.com/mcp
Transport: Streamable HTTP over HTTPS
Auth:      Authorization: Bearer <AGENTPMT_BEARER_TOKEN>
```

Hosted 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.

## Complete Hosted Config Examples

Use this generic shape for MCP clients that accept remote Streamable HTTP servers in a config file:

```json
{
  "mcpServers": {
    "agentpmt": {
      "type": "streamable-http",
      "url": "https://api.agentpmt.com/mcp",
      "headers": {
        "Authorization": "Bearer <AGENTPMT_BEARER_TOKEN>",
        "x-instance-metadata": "{\"client\":\"generic-mcp\",\"platform\":\"remote\"}"
      }
    }
  }
}
```

`x-instance-metadata` is optional. When your client supports custom headers, use it to identify the client and platform in activity logs.

### Cursor / Windsurf / VS Code

If your editor build exposes a remote MCP server option, use the hosted config shape above and set:

    ```text
    URL: https://api.agentpmt.com/mcp
    Authorization: Bearer <AGENTPMT_BEARER_TOKEN>
    ```

    If the editor only accepts command-based MCP servers, use the local STDIO fallback below.

### ChatGPT / Claude browser clients

Browser-based clients usually store remote connector settings in the UI instead of a local file.

    ```text
    Server URL: https://api.agentpmt.com/mcp
    Authentication: Bearer token
    Bearer token: <AGENTPMT_BEARER_TOKEN>
    ```

    Use 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.

### Postman MCP

Create a new MCP request in Postman and use the hosted endpoint as the request URL:

    ```text
    URL: https://api.agentpmt.com/mcp
    Header: Authorization: Bearer <AGENTPMT_BEARER_TOKEN>
    Optional header: x-instance-metadata: {"client":"postman","platform":"desktop"}
    ```

    Connect the request, inspect the loaded tools, run a simple tool call, then verify the call under **Control Center -> Agent Activity**.

## Local STDIO Fallback

Install 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`.

```bash
npm install -g @agentpmt/mcp-router
agentpmt-setup
```

The 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.

## Platform-Specific Local Config Examples

Use 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.

### Claude Desktop

Config files:

    - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
    - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    - Linux: `~/.config/Claude/claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "agentpmt": {
          "command": "npx",
          "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
          "env": {
            "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
            "X_INSTANCE_METADATA": "{\"client\":\"claude_desktop\",\"platform\":\"desktop\"}"
          }
        }
      }
    }
    ```

### Claude Code

Use the command-based MCP config when your Claude Code build does not expose hosted Streamable HTTPS settings.

    ```json
    {
      "mcpServers": {
        "agentpmt": {
          "command": "npx",
          "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
          "env": {
            "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
            "X_INSTANCE_METADATA": "{\"client\":\"claude_code\",\"platform\":\"cli\"}"
          }
        }
      }
    }
    ```

### Cursor

Config file: `~/.cursor/mcp.json`

    ```json
    {
      "mcpServers": {
        "agentpmt": {
          "command": "npx",
          "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
          "env": {
            "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
            "X_INSTANCE_METADATA": "{\"client\":\"cursor\",\"platform\":\"desktop\"}"
          }
        }
      }
    }
    ```

    After saving, open Cursor Settings -> Features -> MCP and refresh servers.

### VS Code

Config files:

    - Windows: `%APPDATA%\Code\User\mcp.json`
    - macOS: `~/Library/Application Support/Code/User/mcp.json`
    - Linux: `~/.config/Code/User/mcp.json`

    ```json
    {
      "mcpServers": {
        "agentpmt": {
          "command": "npx",
          "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
          "env": {
            "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
            "X_INSTANCE_METADATA": "{\"client\":\"vscode\",\"platform\":\"desktop\"}"
          }
        }
      }
    }
    ```

### Windsurf

Config file: `~/.codeium/windsurf/mcp_config.json`

    ```json
    {
      "mcpServers": {
        "agentpmt": {
          "command": "npx",
          "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
          "env": {
            "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
            "X_INSTANCE_METADATA": "{\"client\":\"windsurf\",\"platform\":\"desktop\"}"
          }
        }
      }
    }
    ```

### Zed

Config files:

    - Windows: `%APPDATA%\Zed\settings.json`
    - macOS/Linux: `~/.config/zed/settings.json`

    ```json
    {
      "context_servers": {
        "agentpmt": {
          "settings": {},
          "command": {
            "path": "npx",
            "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
            "env": {
              "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
              "X_INSTANCE_METADATA": "{\"client\":\"zed\",\"platform\":\"desktop\"}"
            }
          }
        }
      }
    }
    ```

### Codex CLI

Config file: `~/.codex/config.toml`

    ```toml
    [mcp_servers.agentpmt]
    command = "npx"
    args = ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"]

    [mcp_servers.agentpmt.env]
    AGENTPMT_BEARER_TOKEN = "<AGENTPMT_BEARER_TOKEN>"
    X_INSTANCE_METADATA = '{"client":"codex","platform":"cli"}'
    ```

### Gemini CLI

Config file: `~/.gemini/settings.json`

    ```json
    {
      "mcpServers": {
        "agentpmt": {
          "command": "npx",
          "args": ["--package=@agentpmt/mcp-router@latest", "agentpmt-router"],
          "env": {
            "AGENTPMT_BEARER_TOKEN": "<AGENTPMT_BEARER_TOKEN>",
            "X_INSTANCE_METADATA": "{\"client\":\"gemini\",\"platform\":\"cli\"}"
          }
        }
      }
    }
    ```

## Browser-Based Clients

Use 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.

If 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.

## Postman Testing

Postman is useful for verifying an agent group before you rely on an agent prompt.

1. **Create an MCP request**
   Choose Postman's MCP request type and set the URL to `https://api.agentpmt.com/mcp`.

2. **Add auth and metadata**
   Add `Authorization: Bearer <AGENTPMT_BEARER_TOKEN>`. Optionally add `x-instance-metadata: {"client":"postman","platform":"desktop"}`.

3. **Connect and run a tool**
   Connect, choose one of the loaded tools, fill in the displayed parameters, and run the request.

4. **Verify activity**
   Open **Control Center -> Agent Activity** and confirm the request, response, status, and metadata are logged.

## Troubleshooting

| Symptom | Check |
|---|---|
| No tools appear | Confirm the Bearer token belongs to the agent group you configured and that tools are added to that group. |
| `401` or auth failure | Re-copy the Bearer token, remove extra whitespace, and check whether the token was rotated. |
| Client rejects hosted config | Use the local STDIO fallback; that client likely requires a command-based MCP server. |
| Tool is listed but fails | Bind any required credentials on the Agent Group and review the tool's current schema. |
| Activity log is missing metadata | Confirm the client supports custom headers for hosted MCP or `X_INSTANCE_METADATA` for the local router. |

## Discovery and Protocol Reference

## MCP Endpoint

- https://api.agentpmt.com/mcp

## Native MCP Methods

- `initialize`: Negotiates MCP protocol capabilities and starts a session.
- `notifications/initialized`: Confirms client initialization after a successful initialize call.
- `tools/list`: Returns the currently available native tool set for the authenticated context.
- `tools/call`: Invokes a selected native tool by name with tool-specific arguments.

## Fetch Native Tools And Call Them

### 1) Initialize

```bash
curl -X POST "https://api.agentpmt.com/mcp" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": {
      "name": "agentpmt-docs-example-client",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {}
    }
  }
}'
```

### 2) List current native tools

```bash
curl -X POST "https://api.agentpmt.com/mcp" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}'
```

### 3) Call a tool returned by tools/list

```bash
curl -X POST "https://api.agentpmt.com/mcp" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool_name_from_tools_list>",
    "arguments": {
      "example_input": "value"
    }
  }
}'
```

## Get More Tools

### 1) Browse available external tools

```bash
curl -X GET "https://www.agentpmt.com/api/external/tools?limit=20"
```

### 2) Create an auth session for wallet signing

```bash
curl -X POST "https://www.agentpmt.com/api/external/auth/session" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0xYOUR_WALLET"
  }'
```

### 3) Invoke a selected tool

```bash
curl -X POST "https://www.agentpmt.com/api/external/tools/{productSlug}/actions/{actionSlug}/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0xYOUR_WALLET",
    "session_nonce": "<session_nonce>",
    "request_id": "<unique_request_id>",
    "signature": "0x<wallet_signature>",
    "parameters": {
      "example": "value"
    }
  }'
```

## Well-Known Discovery URLs

- https://api.agentpmt.com/.well-known/oauth-authorization-server
- https://api.agentpmt.com/.well-known/oauth-protected-resource
- https://api.agentpmt.com/.well-known/openai-apps-challenge
- https://api.agentpmt.com/.well-known/openid-configuration
- https://www.agentpmt.com/.well-known/agent-card.json
- https://www.agentpmt.com/.well-known/agent.json
- https://www.agentpmt.com/.well-known/mcp
- https://www.agentpmt.com/.well-known/mcp/server-card.json
- https://www.agentpmt.com/.well-known/mcp/server.json

## OAuth

- https://api.agentpmt.com/oauth/authorize
- https://api.agentpmt.com/oauth/jwks.json
- https://api.agentpmt.com/oauth/register
- https://api.agentpmt.com/oauth/token

## Related API Reference Links

Raw Bearer-token API callers should use [Programmatic Access](/docs/api-reference/programmatic-access). Wallet-authenticated autonomous agents should use the [Autonomous Agents API](/docs/api-reference/autonomous-agents). Agents paying for one eligible tool action with direct x402 should use [X402 Payments For Tool Usage](/docs/autonomous-agents/x402-payments-for-tool-usage).

- [API To MCP Tool Conversion](/docs/agent-connections/api-to-mcp-tool-conversion) - Create a private Connected API tool, authorize it for an Agent Group, and call it over MCP.