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.

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.

Claude Desktop

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

{
  "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"
      }
    },
    "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"
      }
    }
  }
}

Restart Claude Desktop after saving. The connected servers appear in the tool panel.

Cursor / VS Code

Add the same JSON block to your editor's MCP settings file (.cursor/mcp.json for Cursor, or the VS Code MCP extension config). The structure is identical — 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

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.

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

Step 2: Construct the MCP endpoint URL​

Step 3: Add the server to your MCP client​

Claude Desktop​

Cursor / VS Code​

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

Step 2: Construct the MCP endpoint URL

Step 3: Add the server to your MCP client

Claude Desktop

Cursor / VS Code

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