Version: v2.0

aiXplain MCP Servers

aiXplain exposes 900+ Marketplace models and tools as hosted MCP servers. Any MCP-capable client — Claude Desktop, Cursor, VS Code, or your own agent — can connect to them with a single PAYG API key. No server setup, no credential juggling per vendor.

This guide walks you through discovering assets, constructing endpoints, wiring them into an MCP client, and testing end-to-end.

Prerequisites

An aiXplain account with a PAYG API key — create one at Console > Settings > Keys.
An MCP-capable client (Claude Desktop, Cursor, VS Code with MCP extension, or the aiXplain SDK).
pip install aixplain if you plan to discover assets via the SDK.

Step 1: Find the asset you want to expose

Every Marketplace model or tool has a unique asset path (e.g. openai/gpt-4o-mini/openai) or asset ID (e.g. 6646261c6eb563165658bbb1). You need one of these to build the MCP endpoint URL.

Option A — Browse Studio

Go to aiXplain Studio → Browse.
Search for your model or tool.
Open the asset card and copy the asset path or asset ID.

Option B — Search with the SDK

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

# Search for a model
models = aix.Model.search(query="gpt-4o-mini", page_size=10)
for model in models.results:
    print(model.id, getattr(model, "path", None), model.name)

# Search for a tool
tools = aix.Tool.search(q="tavily", page_size=5)
for tool in tools.results:
    print(tool.id, getattr(tool, "path", None), tool.name)

Show output

Note down either the id or the path — you will use it in the next step.

Option C — aiXplain Marketplace Search tool

aiXplain Marketplace Search is an aiXplain-managed utility tool that searches and inspects the marketplace from inside an agent, script, or MCP client. Find agents, models, tools, and integrations by keyword; filter by modality, developer, supplier, or host; pull full details (function, supplier, pricing, status); and read result counts per asset type — then hand the id or path it returns to Step 2.

It is itself exposed as a hosted MCP server, so you can add it to your client and discover assets conversationally, then expose anything it finds with the steps below. Its asset ID is 6960f934f316da19e5f22494:

https://models-mcp.aixplain.com/mcp/6960f934f316da19e5f22494

Add it like any other asset using the config shapes in Step 3. See the aiXplain Marketplace Search tool page for the full action list and filters.

Step 2: Construct the MCP endpoint URL

The base endpoint pattern is:

https://models-mcp.aixplain.com/mcp/<ASSET_ID_OR_ENCODED_PATH>

You can use either format:

Format	Example
Asset ID	`https://models-mcp.aixplain.com/mcp/6646261c6eb563165658bbb1`
URL-encoded path	`https://models-mcp.aixplain.com/mcp/openai%2Fgpt-4o-mini%2Fopenai`
Raw path (also works)	`https://models-mcp.aixplain.com/mcp/openai/gpt-4o-mini/openai`

tip

URL-encoded paths (forward slashes replaced with %2F) are the recommended canonical form. Underscore-substituted paths do not work.

Step 3: Add the server to your MCP client

Every request to the MCP endpoint must include your PAYG API key in the Authorization header. There are two config shapes — pick the one that matches how your client connects:

Shape	Use it for	How it connects
Stdio bridge (`mcp-remote`)	Claude Desktop, older Cursor	A local `npx mcp-remote` process proxies the remote endpoint over stdio
Direct HTTP (Streamable HTTP)	Claude Code, VS Code, newer Cursor	The client connects straight to the `url`

Which one?

If your client's MCP config expects a command / args, use the stdio bridge. If it accepts a url, use direct HTTP. Clients that read claude_desktop_config.json (Claude Desktop) only support command servers — they cannot consume a bare url, so they need the bridge.

Stdio bridge (`mcp-remote`) — Claude Desktop, older Cursor

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on Windows, and add entries under mcpServers:

{
  "mcpServers": {
    "gpt4o_mini": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://models-mcp.aixplain.com/mcp/openai%2Fgpt-4o-mini%2Fopenai",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <AIXPLAIN_APIKEY>",
        "PATH": "/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

Restart Claude Desktop after saving. The connected server appears in the tool panel.

note

Pass the key via env.AUTH_HEADER + --header Authorization:${AUTH_HEADER}. A literal space inside an args entry (e.g. "Authorization: Bearer ...") breaks mcp-remote, so the value is moved to an env var.
Requires Node.js 18+. On Apple Silicon npx usually lives at /opt/homebrew/bin/npx — keep its directory on PATH (use the full path as command if it is not on PATH).
Add one entry per asset; give each a descriptive key.

Direct HTTP (Streamable HTTP) — Claude Code, VS Code, newer Cursor

For clients with native remote-MCP support, connect straight to the URL:

{
  "mcpServers": {
    "gpt4o_mini": {
      "url": "https://models-mcp.aixplain.com/mcp/openai%2Fgpt-4o-mini%2Fopenai",
      "headers": {
        "Authorization": "Bearer <AIXPLAIN_APIKEY>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Add this block to your client's MCP settings (.cursor/mcp.json for Cursor, the VS Code MCP extension config, or claude mcp add --transport http <name> <url> --header "Authorization: Bearer <key>" for Claude Code). The structure is one key per server — url plus headers.

Custom MCP client or SDK

If you are building your own client, pass the headers on every request. The endpoint returns SSE-formatted responses — parse the data: line to extract the JSON payload:

import httpx, json

AIXPLAIN_APIKEY = "YOUR_API_KEY"
ENDPOINT = "https://models-mcp.aixplain.com/mcp/openai%2Fgpt-4o-mini%2Fopenai"

headers = {
    "Authorization": f"Bearer {AIXPLAIN_APIKEY}",
    "Accept": "application/json, text/event-stream",
    "Content-Type": "application/json",
}

# List available tools on this MCP server
response = httpx.post(
    ENDPOINT,
    headers=headers,
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
    timeout=30,
)
# Parse SSE response
data = json.loads([l for l in response.text.splitlines() if l.startswith("data:")][0][5:])
print(json.dumps(data, indent=2))

Show output

note

The inputSchema above is abridged for readability — this model also accepts fields such as template, prompt, context, language, script, history, and tools. Always call tools/list to get the full, current schema for any asset; schemas vary by asset and can change.

Step 4: Test the connection

Before relying on an MCP server in production, verify it responds correctly.

The MCP endpoint returns SSE-formatted responses (event: message\ndata: {...}). The examples below show how to parse them. MCP clients such as Claude Desktop and Cursor handle this automatically.

The tool name used in tools/call is dynamic — always call tools/list first to get the exact name the server exposes.

Test a model endpoint

import httpx, json

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://models-mcp.aixplain.com/mcp/openai%2Fgpt-4o-mini%2Fopenai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json, text/event-stream",
    "Content-Type": "application/json",
}

# Step 1 — discover the tool name
list_resp = httpx.post(
    ENDPOINT,
    headers=headers,
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
    timeout=30,
)
data = json.loads([l for l in list_resp.text.splitlines() if l.startswith("data:")][0][5:])
tool_name = data["result"]["tools"][0]["name"]
print("Tool name:", tool_name)

# Step 2 — call the tool
response = httpx.post(
    ENDPOINT,
    headers=headers,
    json={
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": {"text": "What is the capital of France?"},
        },
    },
    timeout=30,
)
data = json.loads([l for l in response.text.splitlines() if l.startswith("data:")][0][5:])
print(data["result"]["content"][0]["text"])

Show output

Test a tool endpoint

import httpx, json

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://models-mcp.aixplain.com/mcp/tavily%2Ftavily-web-search%2Ftavily"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json, text/event-stream",
    "Content-Type": "application/json",
}

# Step 1 — discover the tool name
list_resp = httpx.post(
    ENDPOINT,
    headers=headers,
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
    timeout=30,
)
data = json.loads([l for l in list_resp.text.splitlines() if l.startswith("data:")][0][5:])
tool_name = data["result"]["tools"][0]["name"]
print("Tool name:", tool_name)

# Step 2 — call the tool
response = httpx.post(
    ENDPOINT,
    headers=headers,
    json={
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": {"query": "latest AI research 2025", "num_results": "3"},
        },
    },
    timeout=30,
)
data = json.loads([l for l in response.text.splitlines() if l.startswith("data:")][0][5:])
print(data["result"]["content"][0]["text"][:300])

Show output

Step 5: Use multiple assets together

You can register as many aiXplain MCP servers as you need — one entry per asset. Give each a descriptive key so your client can distinguish them. The example below uses the direct HTTP shape; on a stdio-bridge client, repeat the command/args/env form from Step 3 once per asset instead.

{
  "mcpServers": {
    "gpt4o_mini": {
      "url": "https://models-mcp.aixplain.com/mcp/openai%2Fgpt-4o-mini%2Fopenai",
      "headers": {
        "Authorization": "Bearer <AIXPLAIN_APIKEY>",
        "Accept": "application/json, text/event-stream"
      }
    },
    "whisper_asr": {
      "url": "https://models-mcp.aixplain.com/mcp/openai%2Fwhisper-large-v3%2Fopenai",
      "headers": {
        "Authorization": "Bearer <AIXPLAIN_APIKEY>",
        "Accept": "application/json, text/event-stream"
      }
    },
    "tavily_search": {
      "url": "https://models-mcp.aixplain.com/mcp/tavily%2Ftavily-web-search%2Ftavily",
      "headers": {
        "Authorization": "Bearer <AIXPLAIN_APIKEY>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Each server is independent — your client decides which to invoke based on the task at hand.

Asset type reference

Asset type	What to use	Typical use cases
Model	Encoded model path or asset ID	Add a hosted LLM, ASR, TTS, or vision model to your MCP client
Tool	Encoded tool path or asset ID	Expose search, retrieval, PDF parsing, or embedding tools

Troubleshooting

401 Unauthorized Your API key is missing or wrong. Confirm the Authorization: Bearer <key> header is present on every request and the key is a valid PAYG key from Console > Settings > Keys.

404 Not Found The asset path or ID does not exist or is not MCP-enabled. Double-check the path in Studio. Try the asset ID instead of the path.

Path not resolving Underscore-substituted paths (e.g. openai_gpt-4o-mini_openai) do not work. Use URL-encoded paths (%2F) or raw slash paths.

Empty tools/list response The asset exists but has no MCP-exposed actions. Try a different asset or check its Marketplace page for MCP support status.

Streaming not working Make sure Accept: application/json, text/event-stream is included in headers. Some clients require explicit SSE support to be enabled.

Notes

The same endpoint pattern works for models and tools — only the path segment changes.
Marketplace paths must be URL-encoded (/ → %2F) before appending to /mcp/.
One PAYG API key gives access to all assets the key has permission for.
text/event-stream support lets MCP clients that rely on streaming work against supported aiXplain-hosted assets.

Prerequisites​

Step 1: Find the asset you want to expose​

Option A — Browse Studio​

Option B — Search with the SDK​

Option C — aiXplain Marketplace Search tool​

Step 2: Construct the MCP endpoint URL​

Step 3: Add the server to your MCP client​

Stdio bridge (mcp-remote) — Claude Desktop, older Cursor​

Direct HTTP (Streamable HTTP) — Claude Code, VS Code, newer Cursor​

Custom MCP client or SDK​

Step 4: Test the connection​

Test a model endpoint​

Test a tool endpoint​

Step 5: Use multiple assets together​

Asset type reference​

Troubleshooting​

Notes​

Prerequisites

Step 1: Find the asset you want to expose

Option A — Browse Studio

Option B — Search with the SDK

Option C — aiXplain Marketplace Search tool

Step 2: Construct the MCP endpoint URL

Step 3: Add the server to your MCP client

Stdio bridge (`mcp-remote`) — Claude Desktop, older Cursor

Direct HTTP (Streamable HTTP) — Claude Code, VS Code, newer Cursor

Custom MCP client or SDK

Step 4: Test the connection

Test a model endpoint

Test a tool endpoint

Step 5: Use multiple assets together

Asset type reference

Troubleshooting

Notes