# MCP setup

One API for Agents runs a remote MCP server. Add one URL to your agent and approve access in the browser; there is no API key to copy.

```text title=MCP server URL
https://mcp.oneapiforagents.com/mcp
```

- **Transport:** streamable HTTP.
- **Auth:** OAuth 2.1 with PKCE and dynamic client registration, per the MCP authorization spec. Clients discover everything from the server URL.
- **Consent:** when you approve an agent, you pick the workspace, **read-only** or **read-write** access, and which clients the agent can see. Read-only is the default.

## Claude (claude.ai and Claude Desktop)

Custom connectors work on Free, Pro, Max, Team and Enterprise plans.

1. Open **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Paste the server URL and click **Add**.
4. Click **Connect**, sign in to One API for Agents and approve access.

On Team and Enterprise plans an owner first adds the connector under **Organization settings → Connectors**; members then connect it from **Customize → Connectors**. Connectors added on claude.ai are also available in Claude Desktop. Turn it on per conversation from the **+** menu under **Connectors**.

## Claude Code

```sh
claude mcp add --transport http one-api https://mcp.oneapiforagents.com/mcp
```

Then run `/mcp` inside Claude Code, pick **one-api** and sign in. Add `--scope user` to make the server available in every project, or `--scope project` to share it with your team through `.mcp.json`.

## Codex CLI

```sh
codex mcp add one-api --url https://mcp.oneapiforagents.com/mcp
codex mcp login one-api
```

Or add it to `~/.codex/config.toml` yourself, then run `codex mcp login one-api`:

```toml
[mcp_servers.one-api]
url = "https://mcp.oneapiforagents.com/mcp"
```

## Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "one-api": {
      "url": "https://mcp.oneapiforagents.com/mcp"
    }
  }
}
```

Cursor shows the server in its MCP settings with a sign-in prompt. Approve access in the browser window that opens.

## Any other MCP client

Point any client that supports remote servers over streamable HTTP at the server URL. It discovers the OAuth endpoints from the server (protected-resource metadata), registers itself and opens the browser for consent.

For a client that only launches local (stdio) servers, bridge with [mcp-remote](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "one-api": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.oneapiforagents.com/mcp"]
    }
  }
}
```

## Tools

| Tool | What it does |
| --- | --- |
| `whoami` | The workspace the agent is connected to, its access level (read or read-write) and the clients it can see. |
| `list_connections` | Connections the agent can see, with id, provider, label, client and status. |
| `list_endpoints` | Raw endpoints and smart tools for a provider, with input schemas. |
| `call` | Call any raw endpoint or smart tool. Takes the same fields as [`POST /v1/call`](/docs/rest-api.md#post-v1-call). |

Smart tools are also exposed directly by name:

- `gsc_top_queries` (Google Search Console): Top search queries by clicks for a property over the last N days.
- `gsc_quick_wins` (Google Search Console): Queries ranking just off page one (default positions 8–20) with meaningful impressions, sorted by impressions.
- `ga4_traffic_by_page` (Google Analytics 4): Top landing pages by sessions, with users and engagement rate, over the last N days.
- `ga4_list_properties` (Google Analytics 4): Every GA4 property this connection can read, with its account, as a flat list.
- `bing_top_queries` (Bing Webmaster Tools): Top Bing search queries by clicks for a site over the last N days, with impressions, CTR and average position. Bing updates this weekly.
- `bing_top_pages` (Bing Webmaster Tools): Top pages in Bing search by clicks for a site over the last N days, with impressions, CTR and average position.
- `bing_crawl_health` (Bing Webmaster Tools): Crawl health for a site in Bing: pages in index, crawl and HTTP error totals over the last N days, and the URLs with crawl issues (most linked first).
- `bing_list_sites` (Bing Webmaster Tools): Sites on the connected Bing Webmaster account and whether each is verified.
- `sheets_read` (Google Sheets): Read a tab or range as rows of objects keyed by the header row. Capped by `limit`; page with `offset`.
- `sheets_list_tabs` (Google Sheets): The spreadsheet's title, URL and tabs, with each tab's grid size (rows × columns, including empty cells).
- `sheets_append_rows` (Google Sheets): Append rows below a tab's existing data. Pass objects keyed by header name, or arrays in column order.
- `sheets_update_range` (Google Sheets): Overwrite cells starting at a range with rows of values.
- `sheets_create` (Google Sheets): Create a spreadsheet in the connected Google account's Drive, optionally with a frozen header row. Returns its ID and URL. Needs a Google sign-in connection (service accounts can't own files).
- `docs_read` (Google Docs): Read a Google Doc as markdown-style text (headings, lists, tables, links), with its title, revisionId, tabs, heading outline with indexes, and endIndex.
- `docs_create` (Google Docs): Create a Google Doc with a title and optional initial text (markdown headings, lists and paragraphs become Docs styles). Returns its ID and URL.
- `docs_append` (Google Docs): Append text or simple markdown to the end of a Google Doc (or of one tab).
- `docs_replace_text` (Google Docs): Replace every occurrence of some text in a Google Doc. Case-sensitive unless match_case is false.
- `docs_insert` (Google Docs): Insert text or simple markdown into a Google Doc, either below a heading (matched by its text) or at an index from docs_read. Pass exactly one of heading or index.

Every call an agent makes over MCP goes through the same pipeline as the REST API and shows up in **Call logs**.

## Try it

Once connected, ask your agent something like:

> Which queries for example.com rank between positions 8 and 20 with over 100 impressions in the last 28 days? Suggest a title tweak for the top five pages.

The agent will call `gsc_quick_wins`, then read the pages it needs.

## Revoking access

Remove the server in your client, or open **Connect agents** in the dashboard and click **Disconnect**. Access stops on the agent's next call, and its tokens are revoked.