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

# Model Context Protocol (MCP)

> Connect Claude, Cursor, VS Code, and other MCP clients to Tirdad with the Tirdad MCP server

The Tirdad Model Context Protocol (MCP) server provides a set of tools that AI agents can use to interact with the Tirdad API: customers, plans, subscriptions, invoices, payments, events, and more.

## What is the Tirdad MCP server?

* An MCP server that exposes your Tirdad API as **MCP tools** so AI assistants can call your API without reading REST docs.
* Runs on your machine with npx and connects to the Tirdad API with your API key.
* Works with any MCP client that runs local (stdio) servers: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, and others.

## Authenticating the MCP server

Pass your API key with `--api-key-auth`. The server works in the key's environment (sandbox or production). Create keys in the dashboard under **Developers**. See [Manage API keys](https://docs.tirdad.ai/docs/rbac/manage-api.md).

## MCP server security and credentials

* To limit an agent, use an API key with a restricted role, or start the server with `--scope read`.
* Do not commit API keys. Rotate a key if it is ever committed or exposed.
* We recommend enabling human confirmation for write or destructive operations in your MCP client.

> [!WARNING]
>
> We advise caution when giving LLMs write access to production data. Always
> review actions before execution. Use caution when using the Tirdad MCP with
> other servers to avoid prompt injection attacks.

## Installing the Tirdad MCP server

This needs Node.js 20 or later and an API key.

```bash theme={null}
npx -y @tirdad/mcp-server start --server-url https://api.tirdad.ai/v1 --api-key-auth YOUR_API_KEY
```

> [!WARNING]
>
> Always pass `--server-url https://api.tirdad.ai/v1`, with `/v1` and no trailing slash.

In an MCP client config file (Cursor, Windsurf, Claude Desktop, and most others):

```json theme={null}
{
  "mcpServers": {
    "tirdad": {
      "command": "npx",
      "args": [
        "-y",
        "@tirdad/mcp-server",
        "start",
        "--server-url",
        "https://api.tirdad.ai/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}
```

In Claude Code:

```bash theme={null}
claude mcp add tirdad -- npx -y @tirdad/mcp-server start --server-url https://api.tirdad.ai/v1 --api-key-auth YOUR_API_KEY
```

**Config file locations:** Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`. Save the file and restart the client.

**Limit the tools.** Add `"--scope", "read"` to the arguments for read-only access. Repeat `--scope` to combine `read`, `write`, and `delete`. Without `--scope`, every tool is mounted. Add `"--mode", "dynamic"` to expose three discovery tools (`list_tools`, `describe_tool_input`, `execute_tool`) instead of one tool per operation.

## What can you ask the MCP server?

Once connected, you can ask your AI assistant to:

* "List my customers" or "Get customer by id …"
* "Create a subscription for customer … on plan …"
* "Get plan by id …" or "List plans"
* "Get usage for subscription …"

## Which tools the MCP server exposes

The server exposes the Tirdad API as MCP tools (one tool per OpenAPI operation). We recommend enabling human confirmation of tools and exercising caution when using the Tirdad MCP with other servers to avoid prompt injection attacks.

| Resource | Example tools |
| - | - |
| Customers | `get_customers`, `post_customers`, `get_customers_id` |
| Plans | `get_plans`, `get_plans_id`, `post_plans` |
| Subscriptions | `post_subscriptions`, `get_subscriptions_id`, `post_subscriptions_id_cancel` |
| Invoices | `get_invoices`, `get_invoices_id`, `post_invoices` |
| Payments | `get_payments`, `post_payments` |
| Events | `post_events`, `post_events_bulk` |
| Features | `get_features`, `post_features` |
| Prices | `get_prices`, `post_prices` |
| Wallets | `get_wallets_id`, `post_wallets_id_top_up` |

For the full list, see your MCP client's tool list after connecting or the [API Reference](https://docs.tirdad.ai/api-reference/introduction.md).

## Troubleshooting the MCP server

| Symptom | Fix |
| - | - |
| Server does not appear | Save the MCP config and restart your client. |
| Invalid URL or 404 | `--server-url` must be the API base URL with `/v1` and no trailing slash, for example `https://api.tirdad.ai/v1`. |
| API or connection errors | Verify your API key. Test it with `curl -H "x-api-key: YOUR_KEY" https://api.tirdad.ai/v1/customers`. |
| Rate limiting | Reduce request frequency or contact Tirdad support. |

## Related MCP and API references

* [API Reference](https://docs.tirdad.ai/api-reference/introduction.md): full list of Tirdad API operations (each maps to an MCP tool).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.