> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapping.travel/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools for agents

> List, observe, pause, and chat with your agents from Claude Desktop, Cursor, Continue, or the Inspector.

The mapping.travel MCP server exposes a read + chat subset of the agents surface so you can manage agents from your favourite LLM client. **All new agent tools require a Pro Max subscription** — the server returns a typed 403 on non-Pro-Max workspaces.

## New tools

| Tool                       | Mutating?                     | Description                                                |
| -------------------------- | ----------------------------- | ---------------------------------------------------------- |
| `list_agents`              | No                            | All agents in the workspace.                               |
| `get_agent`                | No                            | Single agent with current status, scope, rule-set summary. |
| `list_agent_runs`          | No                            | Recent runs for an agent (filter by status, since).        |
| `get_agent_run`            | No                            | One run with optional step inclusion.                      |
| `list_agent_pending_items` | No                            | Open pending items across one agent or all.                |
| `list_agent_threads`       | No                            | Conversation threads owned by the calling user.            |
| `chat_with_agent`          | Yes (creates message + cycle) | Send a message, get the reply. Non-streaming over MCP.     |
| `pause_agent`              | Yes                           | Idempotent.                                                |
| `resume_agent`             | Yes                           | Idempotent.                                                |
| `get_agent_costs`          | No                            | MTD vs cap, per-day breakdown.                             |
| `list_agent_data_sources`  | No                            | All configured sources + sinks.                            |

`chat_with_agent` is **not idempotent** — each call creates a thread message and (potentially) a cycle.

## Per-client setup

You need an API key from **Developers → MCP** in the app. The setup is identical to the existing MCP setup; the new agent tools appear automatically once your workspace is on Pro Max.

<Tabs>
  <Tab title="Claude Desktop">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null} theme={null}
    {
      "mcpServers": {
        "mapping-travel": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@0.1.37",
            "https://mcp.mapping.travel/mcp",
            "--header",
            "X-API-Key: mt_mcp_live_..."
          ]
        }
      }
    }
    ```

    Restart Claude Desktop. You should see \~29 tools under the wrench icon (18 existing + 11 new agent tools).

    Try: *"List my agents and show me the open pending items for the first one."*
  </Tab>

  <Tab title="Cursor">
    Edit `~/.cursor/mcp.json`:

    ```json theme={null} theme={null}
    {
      "mcpServers": {
        "mapping-travel": {
          "url": "https://mcp.mapping.travel/mcp",
          "headers": { "X-API-Key": "mt_mcp_live_..." }
        }
      }
    }
    ```

    **Settings → MCP** should show 29 tools.
  </Tab>

  <Tab title="Continue">
    Edit `~/.continue/config.json`:

    ```json theme={null} theme={null}
    {
      "experimental": {
        "modelContextProtocolServers": [
          {
            "transport": {
              "type": "streamable-http",
              "url": "https://mcp.mapping.travel/mcp",
              "headers": { "X-API-Key": "mt_mcp_live_..." }
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="MCP Inspector">
    For a quick visual check without configuring a long-running client:

    ```bash theme={null}
    npx @modelcontextprotocol/inspector
    ```

    Pick **Streamable HTTP**, URL `https://mcp.mapping.travel/mcp`, header `X-API-Key: mt_mcp_live_...`, click **Connect**. You can invoke any of the 29 tools from the form.
  </Tab>
</Tabs>

## Tier gating

If your workspace is not on Pro Max, calls to any `list_agent_*`, `chat_with_agent`, `pause_agent`, `resume_agent`, or `get_agent_costs` return:

```json theme={null}
{
  "type": "https://mapping.travel/errors/plan-required",
  "title": "Pro Max plan required",
  "status": 403,
  "requiredPlan": "PROFESSIONAL_MAX",
  "currentPlan": "PROFESSIONAL"
}
```

The non-agent tools (mapping, search, inventory) continue to work normally.

## Streaming

`chat_with_agent` is **non-streaming over MCP** — transports behave inconsistently across clients, and most TUI usage prefers complete replies with a summary of the tool calls the agent made. Streaming chat stays UI-only (the app uses SSE).

## Authorization

| Role             | Can do                                  |
| ---------------- | --------------------------------------- |
| `OWNER`, `ADMIN` | Everything above plus pause/resume.     |
| `MEMBER`         | Read + `chat_with_agent` (rate-capped). |

## Troubleshooting

See [MCP troubleshooting](/mcp/troubleshooting) — the agent tools share the same transport, so any connectivity issue affects all 29 tools uniformly.

## Related

* [Agents overview](/agents/overview) — why you'd want to chat with an agent.
* [MCP connect](/mcp/connect) — the original per-client connection guide.