> ## Documentation Index > Fetch the complete documentation index at: https://docs.nexllm.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP integration *Last edited: 25 Oct 2026 (Asia/Hong\_Kong)* Connect your AI agent to NexLLM over the Model Context Protocol. List models, look up pricing, and generate text or images from inside Claude, Cursor, Codex, and other MCP clients. > [!NOTE] > > The hosted MCP server is **live** at `https://mcp.nexllm.ai/mcp`. Auth is OAuth 2.1 with API-key paste on `connect.nexllm.ai`, and Dynamic Client Registration is available. **Cursor** Custom MCP Connect (Agents web and Desktop) and live tools are verified on Production. A separate hand-click **GUI Pass** for every Claude build is **not** claimed on this page — use the steps below; if a client UI changes, reconnect or use the static client IDs listed. For **custom skills**, prefer [Cursor Desktop](https://docs.nexllm.ai/integrations/skills.md). ## Introduction NexLLM exposes a hosted MCP server at `https://mcp.nexllm.ai`. Connect any MCP-compatible agent (Claude, Cursor, Codex, VS Code, and other clients) and the agent gets a focused set of tools for model discovery, pricing, text generation, and image generation. Models are the same identifiers you already use on the NexLLM gateway, so anything available to your API key is one tool call away. Auth runs on OAuth 2.1 with an API-key form on first connect. The MCP client speaks standard OAuth, but the credential you provide is your NexLLM API key, entered once into a page served by `connect.nexllm.ai`. The key stays server-side, encrypted in the OAuth session, and the client only ever holds the OAuth token. Spend lands on your [www.nexllm.ai](https://www.nexllm.ai) wallet for that key — there is no MCP-specific surcharge. ## Prerequisites Before you connect: * A NexLLM account at [www.nexllm.ai](https://www.nexllm.ai) * An API key from the dashboard (keys commonly start with `sk-`; copy the full value shown once at create time) * Wallet balance if you plan to call `generate_text` or `generate_image` * **No IP allowlist** on that key — Claude custom connectors egress from Anthropic’s cloud, so an allowlisted key will fail the authorize step > [!NOTE] > > **Production verified 2026-10-27 HKT:** OAuth PKCE, JWKS RS256 (`kid=nexmcp-rs256-1`), and live tools including `list_models`, `generate_text`, `list_capabilities`, and `model_metadata`. Do not document instance IPs in customer docs. ## Quick connect Paste this URL into any remote MCP client that supports OAuth: ```text theme={null} https://mcp.nexllm.ai/mcp ``` | | | | - | - | | MCP server | `https://mcp.nexllm.ai/mcp` | | Authorize / key-paste | `https://connect.nexllm.ai` | | Dynamic Client Registration | `https://connect.nexllm.ai/oauth/register` (prefer when the client offers Auto-register) | Pick your client and follow the steps below. > [tab] Claude > > **1. Open Claude settings** > > Launch Claude Desktop or open [claude.ai](https://claude.ai) and go to **Customize → Connectors**. > > **2. Add a custom connector** > > Click **Add custom connector**, set the name to `NexLLM`, and paste the server URL: > > ```text theme={null} > https://mcp.nexllm.ai/mcp > ``` > > Prefer the **hosted** custom connector (cloud callback). If the client asks you to configure your own OAuth client, use: > > | Field | Value | > | - | - | > | Client ID | `claude-ai` | > | Client secret | *(leave blank)* | > > Most installs can use **Auto-register** / Dynamic Client Registration when offered — prefer that when available. > > **3. Sign in** > > Click **Connect**. Your browser opens the NexLLM authorize page on `connect.nexllm.ai`. Paste your NexLLM API key, approve the scopes, and return to Claude. The tools appear in the Claude tool tray. > [tab] Claude Code > > **1. Add the MCP** > > From a project directory, register the hosted server: > > ```bash theme={null} > claude mcp add --transport http nexllm https://mcp.nexllm.ai/mcp > ``` > > **2. Sign in** > > Start a session. Claude Code opens the OAuth flow in your browser on first tool call and caches the refresh token. Paste your NexLLM API key on the authorize page when prompted. > > **3. Use it** > > Ask Claude to list models, check pricing, or generate text or images. Tool calls are visible in the conversation log. > [tab] Cursor > > **1. Open MCP settings** > > Use **Cursor Agents** (web) **Custom MCP → Connect**, or **Cursor Desktop** → **Settings → MCP → Add server**. Both paths work for MCP tools after OAuth. Prefer **Desktop** when you also need [custom skills](https://docs.nexllm.ai/integrations/skills.md). > > **2. Paste the URL** > > Choose the HTTP transport and enter: > > ```text theme={null} > https://mcp.nexllm.ai/mcp > ``` > > On Agents web, prefer **Auto-register** / Dynamic Client Registration when offered. On Desktop, if DCR is unavailable or the client asks for a static client ID, add this to `~/.cursor/mcp.json` (or your MCP config): > > ```json theme={null} > { > "mcpServers": { > "nexllm": { > "url": "https://mcp.nexllm.ai/mcp", > "auth": { > "CLIENT_ID": "cursor" > } > } > } > } > ``` > > **3. Sign in** > > Cursor opens the OAuth flow on first use. Paste your NexLLM API key on `connect.nexllm.ai`, approve the scopes, and the NexLLM tools (`list_models`, `model_pricing`, `list_capabilities`, `model_metadata`, `generate_text`, `generate_image`) become available in chat / Agents. > > > [!NOTE] > > > > **MCP tools:** Cursor Agents web Custom MCP Connect and Desktop both work for tool calls. **Skills:** custom nexllm-skills attach is verified on **Cursor Desktop** (`~/.cursor/skills/`) — see [Skills](https://docs.nexllm.ai/integrations/skills.md). Agents web does not load personal / custom skill packs in the Skills picker today. > [tab] VS Code > > **1. Enable Copilot MCP** > > VS Code → Settings → enable Copilot Chat MCP support. > > **2. Add the server** > > Open the MCP settings JSON and add: > > ```json theme={null} > { > "mcp": { > "servers": { > "nexllm": { > "url": "https://mcp.nexllm.ai/mcp" > } > } > } > } > ``` > > **3. Sign in** > > Run the **MCP: List Servers** command, pick `nexllm`, and complete the OAuth flow in your browser. Paste your NexLLM API key when the authorize page asks for it. > [tab] Codex > > **1. Edit \~/.codex/config.toml** > > Codex speaks stdio, not remote OAuth directly. Bridge through `mcp-remote`: > > ```toml theme={null} > [mcp_servers.nexllm] > command = "npx" > args = ["-y", "mcp-remote", "https://mcp.nexllm.ai/mcp"] > ``` > > **2. Sign in** > > Start Codex. The bridge opens the OAuth flow once and caches the token under `~/.mcp-auth`. Paste your NexLLM API key on the authorize page. > > **3. Use it** > > The NexLLM tools show up the same way as any other MCP server. > > > [!NOTE] > > > > Hosted OAuth is the supported path. `mcp-remote` is a community workaround for stdio-only clients; some redirect URIs may need allowlisting before connect succeeds. > [tab] Other > > ### Remote-capable clients > > If the client supports remote MCP with OAuth, point it at: > > ```text theme={null} > https://mcp.nexllm.ai/mcp > ``` > > Prefer Auto-register / Dynamic Client Registration when the client offers it. Fixed public client IDs that still work as a fallback: > > | Client ID | Notes | > | - | - | > | `claude-ai` | Blank secret | > | `cursor` | For Cursor Desktop / static MCP config | > > See the [MCP specification](https://modelcontextprotocol.io) for transport details. > > ### Stdio-only clients > > For clients that only speak stdio, use the community `mcp-remote` bridge: > > ```json theme={null} > { > "command": "npx", > "args": ["-y", "mcp-remote", "https://mcp.nexllm.ai/mcp"] > } > ``` > > There is no official local NexLLM MCP package yet. Hosted OAuth at `https://mcp.nexllm.ai/mcp` is the supported path; use `mcp-remote` only when your client cannot do remote OAuth. ## How it works The hosted server accepts Streamable HTTP MCP at `https://mcp.nexllm.ai/mcp` and proxies tool calls into the NexLLM gateway on your behalf. Your API key carries the account identity, so usage is recorded against your NexLLM wallet — not against an anonymous service account. The first time a client connects, `connect.nexllm.ai` shows a page where you paste your NexLLM API key. The key is stored encrypted in the OAuth session. The MCP client only ever holds the OAuth JWT. Later tool calls send that token; the server unwraps the session server-side and calls the gateway with your key. The agent picks the tool and model from your request and fills in the parameters. You can still name a specific model when you want exact behavior. ## Tools The agent gets a small set of tools, grouped by intent. ### Generate `generate_text` Run a text completion through the NexLLM gateway. Pass a model identifier available to your key, a prompt or messages, and optional generation parameters. Billed at standard gateway rates for that model. Results are returned as structured text (JSON payload in the tool result) — not a streaming chat UI. `generate_image` Generate an image from a text prompt through the NexLLM gateway. Pass a supported image model and prompt. Billed at standard gateway rates. The tool result is **JSON in text** (for example `{ model, created, data: [{ url | b64_json }] }`). Clients may need to open the `url` or decode `b64_json`; native image content blocks are not guaranteed in every MCP client. ### Browse `list_models` List models available through NexLLM for your key. Use search or filters when your client exposes them. Returns model identifiers the agent can hand straight to `generate_text` or `generate_image`. Some filter fields may be ignored until the catalog exposes richer capability metadata — always pick an `id` from the live response. `model_pricing` Look up pricing for a model. Returns rate information so the agent (or you) can estimate cost before generating. Some models may return an empty pricing list; generation can still succeed if you accept unquoted spend. `list_capabilities` Return static supported / unsupported modalities for this MCP server (for example video and audio are listed as unsupported). Use this for discovery — do not invent tools for unsupported modalities. `model_metadata` Return catalog fields for one model id from `list_models`. Useful when an agent needs richer metadata than the list alone. ## Example flows Here's what an agent does when you give it a clear request and the right tools. > List a few GPT models I can use, check pricing for one of them, then write a short product tagline. 1. **`list_models`** — finds models matching your request (for example GPT-family identifiers available to your key). 2. **`model_pricing`** — returns the rate for the chosen model so you can confirm cost. 3. **`generate_text`** — runs the generation; spend is deducted from your NexLLM wallet. A few other patterns come up often. **Compare before you spend.** > What does gpt-4o-mini cost vs a Claude Sonnet model on my key? The agent calls `list_models`, then `model_pricing` for each candidate, and summarizes side by side. Discovery and pricing lookups are intended to be free. **Generate an image.** > Make a simple logo concept: a geometric fox icon on a dark background. The agent picks a supported image model (or the one you name), then calls `generate_image`. You don't have to script the order. The agent decides the tool sequence on its own. ## Auth The hosted server uses OAuth 2.1 with PKCE (S256) as the protocol. The credential is your NexLLM API key — entered on a NexLLM-branded page at `connect.nexllm.ai`, not collected by the client UI. The flow is: 1. The client discovers the protected resource at `https://mcp.nexllm.ai/.well-known/oauth-protected-resource`, which points at the authorization server `https://connect.nexllm.ai`. 2. The client reads authorization-server metadata from `https://connect.nexllm.ai/.well-known/oauth-authorization-server` (including Dynamic Client Registration at `https://connect.nexllm.ai/oauth/register` when the client supports it). 3. The browser opens the authorize page on `connect.nexllm.ai`. You paste your NexLLM API key and approve scopes (`models:read`, `inference:execute`, `pricing:read`). 4. The server stores the key encrypted in the OAuth session and redirects back to the client with tokens. Access tokens are RS256 JWTs; keys are published at `https://connect.nexllm.ai/.well-known/jwks.json`. 5. Subsequent tool calls send the access token in the `Authorization` header. The server recovers your API key server-side and calls the NexLLM gateway on your behalf. The API key never reaches the MCP client. Spend lands on your own NexLLM wallet, because every gateway call uses your key. To revoke access, rotate or delete the API key in your [NexLLM dashboard](https://www.nexllm.ai). The OAuth session still exists, but gateway calls fail until you disconnect the connector in your client and reconnect with a fresh key. > [!WARNING] > > The legitimate flow asks you to paste your NexLLM API key into a NexLLM-branded page on `connect.nexllm.ai`. Any client that prompts for an API key in its own UI before the browser redirect is bypassing OAuth. That pattern is common for stdio-only clients connecting through a bridge — treat it carefully and prefer the hosted OAuth page. ## Troubleshooting > [accordion] The OAuth popup closes immediately and the connector shows as failed > > The browser blocked the popup, or the popup opened but never received the callback. Unblock popups for the client's domain (`claude.ai`, Cursor, etc.) and try connecting again. If the popup opens but closes without completing, disconnect and reconnect the server. Prefer Claude's hosted custom connector or Cursor Desktop when available. > [accordion] I see a token exchange or authentication error after submitting my key > > Locally cached OAuth state is often stale. Clear it and reconnect: > > * Clients using `mcp-remote`: remove `~/.mcp-auth` and restart the client. > * Claude Code: open `/mcp`, clear authentication on the NexLLM entry, then re-add the server. > * Claude Desktop / claude.ai: **Customize → Connectors** → disconnect NexLLM and reconnect. > * Cursor: remove the server from MCP settings and add it again. > > Also confirm the API key has **no IP allowlist** — cloud connectors cannot complete authorize from a locked-down key. > [accordion] The tools don't appear after I connect > > Verify the server is registered and the tool list was fetched: > > * Claude Desktop / claude.ai: **Customize → Connectors** → NexLLM should read Connected. If not, remove and re-add. > * Claude Code: run `claude mcp list`, confirm the entry, then restart the session. > * Codex CLI: run `codex mcp list` and start a new session. > > Then ask the agent something trivial (`list a few models on NexLLM`). If it calls `list_models`, the connection is live. > [accordion] I rotated my API key and the connector still uses the old one > > The OAuth session stored the key at connect time. Rotating the key in the dashboard does not update that session. Disconnect the connector in your client, reconnect, and paste the new key on the authorize page. > [accordion] A generate call failed with insufficient balance or wallet errors > > Your wallet balance was below the model's cost. [Top up your wallet](https://docs.nexllm.ai/account/wallet-and-top-up.md) and have the agent retry. To budget first, ask the agent to call `model_pricing` before `generate_text` or `generate_image`. > [accordion] OAuth fails with a redirect\_uri error > > The client's callback URL may not be registered yet. Prefer Auto-register / DCR when available, or use the recommended path for that client (Claude hosted custom connector, Cursor Desktop) and retry. For stdio bridges such as `mcp-remote`, confirm you are on the latest bridge and that the OAuth popup completed on `connect.nexllm.ai`. > [accordion] generate\_image fails with plugin\_request\_invalid / size limits > > Some Seedream IDs reject the common OpenAI default `1024x1024`. For `byteplus/Dola-Seedream-5.0-lite` and `byteplus/ByteDance-Seedream-4.5`, use **`size: "2048x2048"`** (verified 2026-10-25). Prefer `byteplus/Dola-Seedream-5.0-flash` when you need a 1K square. The gateway returns HTTP 400 `plugin_request_invalid` when the size is outside that model's pixel/aspect limits. > [accordion] generate\_image fails with a gateway error > > Some image model families can return a temporary gateway error (for example no channel under group `auto`). Call `list_models`, pick a known-good image model such as `byteplus/Dola-Seedream-5.0-flash`, and retry `generate_image`. If the error mentions size / `plugin_request_invalid`, see the size accordion above. Confirm wallet balance if the error mentions insufficient funds instead. > > If using a GPT Image id (`nexllm/gpt-image-*`), **omit `response_format`** in the tool/gateway body. If the client/tool defaults it to `url`, prefer Seedream flash or another known-good id until the tool omits the field for GPT Image. ## Pricing MCP tool calls are billed at standard NexLLM gateway pricing for whatever underlying request runs. There is no MCP-specific surcharge. | Tool | Billing | | - | - | | `list_models` | Intended free (discovery) | | `model_pricing` | Intended free (lookup) | | `list_capabilities` | Intended free (discovery) | | `model_metadata` | Intended free (lookup) | | `generate_text` | Standard gateway rates for the model | | `generate_image` | Standard gateway rates for the model | If a `generate_text` call would cost the same amount through `https://www.nexllm.ai/v1`, MCP charges the same amount to the wallet tied to the API key you pasted. For per-model rates, call `model_pricing` from inside the agent or see [Model pricing](https://docs.nexllm.ai/channel-groups/pricing-overview.md). ## Related * [Skills](https://docs.nexllm.ai/integrations/skills.md) — outcome recipes on top of MCP * [Compatible APIs](https://docs.nexllm.ai/integrations/compatible-apis.md) — OpenAI-compatible gateway for app code * [Vercel AI SDK](https://docs.nexllm.ai/integrations/vercel-ai-sdk.md) — AI SDK chat against the same base URL * [API Reference](https://docs.nexllm.ai/api-reference/overview.md) — full gateway endpoints This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.