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.

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.

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 wallet for that key — there is no MCP-specific surcharge.

Prerequisites

Before you connect:

A NexLLM account at 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

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:

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.

Open Claude settings

Launch Claude Desktop or open claude.ai and go to Customize → Connectors.

Add a custom connector

Click Add custom connector, set the name to NexLLM, and paste the server URL:

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.

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.

Add the MCP

From a project directory, register the hosted server:

claude mcp add --transport http nexllm https://mcp.nexllm.ai/mcp

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.

Use it

Ask Claude to list models, check pricing, or generate text or images. Tool calls are visible in the conversation log.

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.

Paste the URL

Choose the HTTP transport and enter:

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):

{
  "mcpServers": {
    "nexllm": {
      "url": "https://mcp.nexllm.ai/mcp",
      "auth": {
        "CLIENT_ID": "cursor"
      }
    }
  }
}

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.

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. Agents web does not load personal / custom skill packs in the Skills picker today.

Enable Copilot MCP

VS Code → Settings → enable Copilot Chat MCP support.

Add the server

Open the MCP settings JSON and add:

{
  "mcp": {
    "servers": {
      "nexllm": {
        "url": "https://mcp.nexllm.ai/mcp"
      }
    }
  }
}

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.

Edit ~/.codex/config.toml

Codex speaks stdio, not remote OAuth directly. Bridge through mcp-remote:

[mcp_servers.nexllm]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.nexllm.ai/mcp"]

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.

Use it

The NexLLM tools show up the same way as any other MCP server.

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.

Remote-capable clients

If the client supports remote MCP with OAuth, point it at:

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 for transport details.

Stdio-only clients

For clients that only speak stdio, use the community mcp-remote bridge:

{
  "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.

list_models — finds models matching your request (for example GPT-family identifiers available to your key).
model_pricing — returns the rate for the chosen model so you can confirm cost.
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:

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.
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).
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).
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.
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. The OAuth session still exists, but gateway calls fail until you disconnect the connector in your client and reconnect with a fresh key.

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

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.

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.

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.

A generate call failed with insufficient balance or wallet errors

Your wallet balance was below the model’s cost. Top up your wallet and have the agent retry. To budget first, ask the agent to call model_pricing before generate_text or generate_image.

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.

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.

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.

Skills — outcome recipes on top of MCP
Compatible APIs — OpenAI-compatible gateway for app code
Vercel AI SDK — AI SDK chat against the same base URL
API Reference — full gateway endpoints

​Introduction

​Prerequisites

​Quick connect

​Remote-capable clients

​Stdio-only clients

​How it works

​Tools

​Generate

​Browse

​Example flows

​Auth

​Troubleshooting

​Pricing

​Related

Introduction

Prerequisites

Quick connect

Remote-capable clients

Stdio-only clients

How it works

Tools

Generate

Browse

Example flows

Auth

Troubleshooting

Pricing

Related