Skip to content

Commit c784fcd

Browse files
kristinaorekhovagitbook-bot
kristinaorekhova
authored and
gitbook-bot
committed
GITBOOK-1147: No subject
1 parent faa3028 commit c784fcd

1 file changed

Lines changed: 49 additions & 123 deletions

File tree

‎docs/quickstart/mcp.md‎

Lines changed: 49 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,20 @@ icon: plug
55

66
# MCP
77

8-
Connect AI/ML API to your AI client — **Claude Desktop, Claude (web), Cursor, Claude Code**, and other MCP-capable apps — over the [Model Context Protocol](https://modelcontextprotocol.io/) using **OAuth**.
8+
Connect AIMLAPI to your AI client — **Claude Desktop, Claude (web), Cursor, Claude Code**, and other MCP-capable apps — over the [Model Context Protocol](https://modelcontextprotocol.io/) using **OAuth**.
99

10-
You sign in with your AI/ML API account in the browser; there is **no API key to copy or paste**. Once connected, you can discover and compare models, run inference (LLM / image / video / audio / embeddings), manage long-running generation jobs, and check your balance — directly from the client.
10+
You sign in with your AIMLAPI account in the browser; there is **no API key to copy or paste**. Once connected, you can discover and compare models, run inference (LLM / image / video / audio / embeddings), manage long-running generation jobs, and check your balance — directly from the client.
1111

1212
Usage is billed to your AIMLAPI account, exactly like the REST API.
1313

14-
{% hint style="info" %}
15-
Prefer to paste an API key instead of signing in? That method is also supported — add an `Authorization: Bearer <YOUR_AIMLAPI_KEY>` header instead of using OAuth. This guide covers the **OAuth** (browser sign-in) flow.
16-
{% endhint %}
17-
18-
***
14+
> Prefer to paste an API key instead of signing in? That method is also supported — add an `Authorization: Bearer <YOUR_AIMLAPI_KEY>` header instead of using OAuth. This guide covers the **OAuth** (browser sign-in) flow.
1915
2016
## Prerequisites
2117

22-
* An **AI/ML API account** — create one at [https://aimlapi.com](https://aimlapi.com/).
18+
* An **AIMLAPI account** — create one at [https://aimlapi.com](https://aimlapi.com/).
2319
* A client that supports **remote MCP servers over Streamable HTTP with OAuth** (all clients below do).
2420
* A balance on your account if you plan to run billable inference (top up at [https://aimlapi.com/app/billing](https://aimlapi.com/app/billing)).
21+
* **A correct system clock.** OAuth tokens are time-sensitive — if your computer's date, time, or time zone is wrong, the sign-in will fail (and some clients won't even start the session). Make sure the clock is set automatically / synced before you begin.
2522

2623
## Endpoint
2724

@@ -33,87 +30,38 @@ You only ever enter this **one URL**. Your client discovers everything else (the
3330

3431
## How the OAuth connection works
3532

36-
{% stepper %}
37-
{% step %}
38-
## Contacts the MCP server
39-
40-
When you add the server URL **without an API key**, your client contacts the MCP server and is told that authentication is required.
41-
{% endstep %}
42-
43-
{% step %}
44-
## Discovers the authorization server
45-
46-
Your client automatically discovers the AIMLAPI authorization server.
47-
{% endstep %}
48-
49-
{% step %}
50-
## Registers and opens your browser
51-
52-
Your client registers itself and opens your browser.
53-
{% endstep %}
54-
55-
{% step %}
56-
## Signs you in and connects
33+
When you add the server URL **without an API key**, your client:
5734

58-
You **sign in to AI/ML API** and **approve access**; the client receives a token and connects.
59-
{% endstep %}
60-
{% endstepper %}
35+
1. Contacts the MCP server and is told that authentication is required.
36+
2. Automatically discovers the AIMLAPI authorization server.
37+
3. Registers itself and opens your browser.
38+
4. You **sign in to AIMLAPI** and **approve access**; the client receives a token and connects.
6139

6240
You never handle a key. The client stores the token securely and refreshes it for you.
6341

64-
***
42+
> **Note on the "Connect" button (Claude Desktop & web).** Adding the connector only _registers_ it — it does not sign you in. After you add it, the connector appears with a **Connect** button; you must click **Connect** to open the browser and complete the AIMLAPI sign-in. Until you click **Connect** and approve, the connector stays added but **not authenticated**, and its tools will not work.
6543
6644
## Claude Desktop
6745

68-
{% stepper %}
69-
{% step %}
70-
## Open the connector settings
46+
1. **Settings → Connectors → Add custom connector.**
47+
2. **Name:** `AIMLAPI` · **Remote MCP server URL:** `https://mcp.aimlapi.com/mcp`
48+
3. Click **Add**. The connector is now registered.
49+
4. Click **Connect** on the AIMLAPI connector. A browser window opens → **sign in to AIMLAPI** → **approve access**.
50+
5. The connector shows **connected**, and the AIMLAPI tools become available in your chats.
51+
6. **Verify:** open a chat and ask _"Use AIMLAPI to check my account balance."_ A returned balance confirms the connection and authorization are working.
7152

72-
Go to **Settings → Connectors → Add custom connector**.
73-
{% endstep %}
74-
75-
{% step %}
76-
## Add AIMLAPI
77-
78-
Set **Name:** `AIMLAPI` · **Remote MCP server URL:** `https://mcp.aimlapi.com/mcp`
79-
{% endstep %}
80-
81-
{% step %}
82-
## Sign in and connect
83-
84-
Click **Add**. A browser window opens → **sign in to AIMLAPI** → **approve access**.
85-
86-
The connector appears as **connected**, and the AI/ML API tools become available in your chats.
87-
{% endstep %}
88-
{% endstepper %}
53+
**Remove:** **Settings → Connectors → AIMLAPI → Remove / Disconnect.**
8954

9055
## Claude (web — claude.ai)
9156

92-
{% stepper %}
93-
{% step %}
94-
## Open connector settings
95-
96-
Open **Settings → Connectors → Add custom connector**.
97-
98-
On Team/Enterprise plans this is done by an Owner under **Organization settings → Connectors**.
99-
{% endstep %}
57+
1. Open **Settings → Connectors → Add custom connector** (on Team/Enterprise plans this is done by an Owner under **Organization settings → Connectors**).
58+
2. Enter the URL `https://mcp.aimlapi.com/mcp` and add it.
59+
3. Click **Connect** on the AIMLAPI connector. A browser flow opens → **sign in to AIMLAPI** → **approve** → connected.
60+
4. **Verify:** ask _"Use AIMLAPI to check my account balance."_
10061

101-
{% step %}
102-
## Add the server URL
62+
> Custom-connector availability depends on your Claude plan.
10363
104-
Enter the URL `https://mcp.aimlapi.com/mcp` and add it.
105-
{% endstep %}
106-
107-
{% step %}
108-
## Complete the browser flow
109-
110-
A browser flow opens → **sign in to AI/ML API** → **approve** → connected.
111-
{% endstep %}
112-
{% endstepper %}
113-
114-
{% hint style="info" %}
115-
Custom-connector availability depends on your Claude plan.
116-
{% endhint %}
64+
**Remove:** **Settings → Connectors → AIMLAPI → Remove.**
11765

11866
## Cursor
11967

@@ -129,84 +77,62 @@ Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).
12977
}
13078
```
13179

132-
{% stepper %}
133-
{% step %}
134-
## Open Cursor tools settings
135-
136-
Open **Cursor Settings → Tools & Integrations**, find **aimlapi**, and click **Login**.
137-
{% endstep %}
80+
Then open **Cursor Settings → Tools & Integrations** and find **aimlapi**. It usually appears **Disabled** first — click **···→ Enable**, then click **Login**. A browser opens → **sign in to AIMLAPI** → **Allow**. The server turns green when connected.
13881

139-
{% step %}
140-
## Sign in and allow access
82+
**Verify:** in an Agent chat, ask _"Using aimlapi, check my account balance."_
14183

142-
A browser opens → **sign in to AI/ML API** → **Allow**.
143-
{% endstep %}
84+
**Remove:** Cursor cannot delete an MCP server from the UI — the **···** menu only offers Configure / Reload / Enable. To remove it, open `~/.cursor/mcp.json` (the **Configure** dialog shows its path) and delete the `aimlapi` block, then **Reload** or restart Cursor. Note: turning off the source toggle only hides the server from the UI — the entry stays in the file until you delete it there.
14485

145-
{% step %}
146-
## Confirm connection
147-
148-
The server turns green when connected.
149-
{% endstep %}
150-
{% endstepper %}
151-
152-
## Claude Code
86+
## Claude Code (CLI)
15387

15488
```bash
15589
claude mcp add --transport http aimlapi https://mcp.aimlapi.com/mcp
15690
```
15791

158-
{% stepper %}
159-
{% step %}
160-
## Open the MCP menu
161-
162-
Inside an interactive Claude Code session, run **`/mcp`**.
163-
{% endstep %}
92+
By default this adds the server in **local** scope — it is only available inside the current folder / project. To make it available everywhere, add `--scope user`:
16493

165-
{% step %}
166-
## Select AIMLAPI
94+
```bash
95+
claude mcp add --transport http --scope user aimlapi https://mcp.aimlapi.com/mcp
96+
```
16797

168-
Select **aimlapi** and choose **Authenticate**.
169-
{% endstep %}
98+
Then, inside an interactive Claude Code session, run **`/mcp`**, select **aimlapi**, and choose **Authenticate** — a browser opens for you to sign in. (Do **not** pass an `--header` flag; that switches the client to API-key auth instead of OAuth.)
17099

171-
{% step %}
172-
## Sign in in the browser
100+
**Verify:** run `claude mcp list` (the server should show as connected), or in a session ask _"Use the aimlapi MCP to check my account balance."_
173101

174-
A browser opens for you to sign in. (Do **not** pass an `--header` flag; that switches the client to API-key auth instead of OAuth.)
175-
{% endstep %}
176-
{% endstepper %}
102+
**Remove:** `claude mcp remove aimlapi` (confirm with `claude mcp list`).
177103

178104
## Other MCP clients
179105

180-
Any client implementing the MCP authorization spec (OAuth 2.1 + PKCE with dynamic client registration) works the same way: point it at `https://mcp.aimlapi.com/mcp` with no API key and complete the browser sign-in.
181-
182-
To inspect the flow step by step, use the MCP Inspector:
106+
Any client implementing the MCP authorization spec (OAuth 2.1 + PKCE with dynamic client registration) works the same way: point it at `https://mcp.aimlapi.com/mcp` with no API key and complete the browser sign-in. To inspect the flow step by step, use the MCP Inspector:
183107

184108
```bash
185109
npx @modelcontextprotocol/inspector@latest
186110
```
187111

188112
Set **Transport = Streamable HTTP**, **URL = `https://mcp.aimlapi.com/mcp`**, then use **Open Auth Settings → Quick OAuth Flow**.
189113

190-
***
191-
192114
## What you can do once connected
193115

194-
* **Discover models** — search and compare the catalog, and get a comparable headline price for each.
116+
* **Discover models** — search and compare the catalog, get a comparable headline price.
195117
* **Run inference** — LLM chat, embeddings, image / video / audio generation.
196118
* **Manage jobs** — submit long-running generations and poll their status/results.
197119
* **Account** — check your balance and usage.
198120

199-
Every call is billed to your AI/ML API account, just like the REST API.
121+
Every call is billed to your AIMLAPI account, just like the REST API.
200122

201123
## Managing the connection
202124

203-
To stop using AI/ML API from a client, **remove or disconnect** the AI/ML API connector in that client's settings.
125+
To stop using AIMLAPI from a client, **remove or disconnect** the AIMLAPI connector — the exact step differs per client:
126+
127+
| Client | How to remove |
128+
| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
129+
| Claude Desktop | Settings → Connectors → AIMLAPI → Remove / Disconnect. |
130+
| Claude (web) | Settings → Connectors → AIMLAPI → Remove. |
131+
| Cursor | Edit `~/.cursor/mcp.json` and delete the `aimlapi` block (cannot be removed from the UI), then Reload / restart Cursor. |
132+
| Claude Code | `claude mcp remove aimlapi`. |
133+
134+
**Clean reinstall.** Removing the connector in the client does not always revoke the OAuth token on the AIMLAPI side. For a fully clean reinstall — one that shows the sign-in / approval screen again — also revoke the app's access in your AIMLAPI account (**Authorized apps / Connections → Revoke**) before adding the server back.
204135

205136
## Troubleshooting
206137

207-
| Symptom | Fix |
208-
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
209-
| Browser didn't open, or the client is stuck "connecting" | Remove the connector and add it again; make sure you completed the AI/ML API sign-in in the browser. |
210-
| Connected, but inference fails with an insufficient-balance error | Top up at [https://aimlapi.com/app/billing](https://aimlapi.com/app/billing). |
211-
| The client connects but never asks you to sign in | You likely added an `Authorization` header — with a header the client uses API-key auth, not OAuth. Remove the header to use OAuth. |
212-
| "Sign-in failed" / authorization error | Confirm you're signing in to the correct AI/ML API account, then retry from the client. |
138+
<table data-search="false"><thead><tr><th>Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>Browser didn't open, or the client is stuck "connecting"</td><td>Remove the connector and add it again; make sure you clicked <strong>Connect</strong> and completed the AIMLAPI sign-in in the browser.</td></tr><tr><td>Session won't start / "clock is set incorrectly" / sign-in fails immediately</td><td>Your system clock is wrong. Set the date, time, and time zone automatically, then retry — OAuth tokens are time-sensitive.</td></tr><tr><td>Connector added but tools don't work</td><td>You likely didn't click <strong>Connect</strong> (Desktop / web) or <strong>Enable + Login</strong> (Cursor). The connector must be authenticated, not just added.</td></tr><tr><td>Server shows <strong>Disabled</strong> in Cursor after editing <code>mcp.json</code></td><td>Open <strong>···→ Enable</strong>, then <strong>Login</strong> to authenticate.</td></tr><tr><td>MCP works in one folder but is missing in another (Claude Code)</td><td>It was added in <strong>local</strong> scope. Re-add with <code>--scope user</code> to make it global.</td></tr><tr><td>Reinstalled but never asked to sign in again</td><td>The old OAuth token is still valid. Revoke the app in <strong>AIMLAPI → Authorized apps</strong>, then reconnect.</td></tr><tr><td>Connected, but inference fails with an insufficient-balance error</td><td>Top up at <a href="https://aimlapi.com/app/billing">https://aimlapi.com/app/billing</a>.</td></tr><tr><td>The client connects but never asks you to sign in</td><td>You likely added an <code>Authorization</code> header — with a header the client uses API-key auth, not OAuth. Remove the header to use OAuth.</td></tr><tr><td>"Sign-in failed" / authorization error</td><td>Confirm you're signing in to the correct AIMLAPI account, then retry from the client.</td></tr></tbody></table>

0 commit comments

Comments
 (0)