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

# Quickstart

> Step-by-step setup for connecting the timepay.ai MCP server to Claude Code, Claude Desktop, Cursor, Windsurf, or another MCP client.

# Quickstart

There is nothing to install: the server is hosted at `mcp.timepay.ai`. Connect using OAuth when your client supports it, or use API-key headers.

```
URL:       https://mcp.timepay.ai/mcp
Header:    X-API-KEY: <your TIMEPAY_API_KEY>
Optional:  X-ORG-ID: <target organization ID>
```

**1. Get your API key**

Get it from the [Console](https://console.timepay.ai). Keep it secret: anyone with the key can read your account data and place calls.

**2. Add the MCP server**

> [!TIP]
>
> Some clients, including Claude Code and Codex, detect OAuth support and start the authorization flow automatically. For clients that do not support OAuth, connect with the `X-API-KEY` header.

> [!NOTE]
>
> If your account belongs to multiple organizations, add the `X-ORG-ID` header with the ID of the organization you want to access. This header is only required when authenticating with `X-API-KEY`. However if you use OAuth, the flow will ask you to select the organization.

**Claude Code**

```bash theme={null}
claude mcp add --transport http timepay https://mcp.timepay.ai/mcp
```

**Claude Desktop**

Claude Desktop only launches local (stdio) servers, so reaching this remote HTTP server needs the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. Add the following to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "timepay": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.timepay.ai/mcp",
        "--header", "X-API-KEY: <your TIMEPAY_API_KEY>"
      ]
    }
  }
}
```

Restart Claude Desktop after saving.

**Cursor**

Add the following to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "timepay": {
      "url": "https://mcp.timepay.ai/mcp",
      "headers": { "X-API-KEY": "<your TIMEPAY_API_KEY>" }
    }
  }
}
```

**Windsurf**

Add the following to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "timepay": {
      "serverUrl": "https://mcp.timepay.ai/mcp",
      "headers": { "X-API-KEY": "<your TIMEPAY_API_KEY>" }
    }
  }
}
```

**Codex CLI**

Connect using OAuth:

```bash theme={null}
codex mcp add timepay --url https://mcp.timepay.ai/mcp
```

Complete the OAuth sign-in flow when prompted.

**Zed**

Add the following to `settings.json`. Zed does not support environment-variable interpolation in headers, so the key goes in directly:

```json theme={null}
{
  "context_servers": {
    "timepay": {
      "url": "https://mcp.timepay.ai/mcp",
      "headers": { "X-API-KEY": "<your TIMEPAY_API_KEY>" }
    }
  }
}
```

**Any other client**

Point it at the URL and header above. If it only launches local (stdio) servers, bridge it with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```bash theme={null}
npx -y mcp-remote https://mcp.timepay.ai/mcp \
  --header "X-API-KEY: <your TIMEPAY_API_KEY>"
```

**3. Verify the connection**

Start a new conversation and ask:

```
List my timepay.ai agents
```

A real list in response means you are connected.

> [!NOTE]
>
> claude.ai (web and mobile) supports OAuth. Add `https://mcp.timepay.ai/mcp` as a custom connector and complete the OAuth sign-in flow.

## Troubleshooting

> **Tools return an auth error**
>
> Check that the header reads exactly `X-API-KEY: <your TIMEPAY_API_KEY>`. If your account belongs to multiple organizations, also send `X-ORG-ID: <target organization ID>`. An invalid key returns a `403` from the underlying timepay.ai API.

> **Client cannot reach a remote HTTP server**
>
> Some clients, including Claude Desktop, only support locally run stdio servers. Use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge shown above.

> **Not sure the server is reachable**
>
> Test it directly with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
>
> ```bash theme={null}
> npx @modelcontextprotocol/inspector
> ```
>
> Connect with transport **Streamable HTTP**, URL `https://mcp.timepay.ai/mcp`, and header `X-API-KEY: <your TIMEPAY_API_KEY>`. Add `X-ORG-ID: <target organization ID>` if your account belongs to multiple organizations.


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