Skip to main content
Version: v2.0

Remote MCP

Connect an agent to a remote MCP server, scope its actions, and run queries against external systems — without rebuilding tools from scratch.

Prerequisites:

  • aiXplain account and API key (get one ↗)
  • pip install aixplain

Quick start​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

# Create and save the MCP tool
mcp_tool = aix.Tool(
    integration="aixplain/mcp-server",
    name="Remote MCP Tool",
    config={"url": "https://remote.mcpservers.org/fetch/mcp"},
)
mcp_tool.save()
mcp_tool.allowed_actions = ["fetch"]

# Create an agent and run
agent = aix.Agent(
    name="MCP Agent",
    description="Fetches a URL via remote MCP and summarises.",
    instructions="Use the MCP tool to fetch page content and summarise key points.",
    tools=[mcp_tool],
)

response = agent.run(query="Give me information about the aiXplain website.")
print(response.data.output)
Show output

Transport protocols​

aiXplain Remote MCP supports both standard MCP transport protocols:

ProtocolURL patternBest for
HTTPhttp://host:port/mcpStateless tools — fetch, search, retrieval
SSEhttp://host:port/sseStreaming or event-based servers, partial outputs

Choose based on your server's capabilities and interaction pattern.

Step 1: Create the MCP tool​

mcp_tool = aix.Tool(
    integration="aixplain/mcp-server",
    name="Remote MCP Tool",
    config={"url": "https://remote.mcpservers.org/fetch/mcp"},
)
mcp_tool.save()

save() persists the tool and makes it usable inside agents.

Step 2: Explore available actions​

Inspect what the MCP server exposes before scoping:

print(mcp_tool.list_actions())

# Inspect a specific action
mcp_tool.actions["fetch"]
Show output

Step 3: Scope allowed actions​

Restrict the tool to only the actions your agent needs:

mcp_tool.allowed_actions = ["fetch"]

When allowed_actions is None or [], all server actions are exposed. Scoping reduces parameter bloat and prevents the agent from using actions you haven't reviewed.

Step 4: Test the tool directly​

Verify the tool works before attaching it to an agent:

result = mcp_tool.run(data={"url": "https://www.aixplain.com"})
print(result)
Show output

Step 5: Create and run the agent​

mcp_agent = aix.Agent(
    name="Remote MCP Demo Agent",
    description="Fetches a page via MCP and summarises.",
    instructions="Call the MCP tool to fetch page content, then summarise the key information in bullets.",
    tools=[mcp_tool],
)

response = mcp_agent.run(query="Summarise key info about https://aixplain.com")
print(response.data.output)
Show output

Use progress_format="logs" to inspect tool invocations during debugging:

response = mcp_agent.run(
    query="Give me information about the aiXplain website.",
    progress_format="logs",
    progress_verbosity=1,
)
print(response.data.output)
Show output

Full example​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

# Tool
mcp_tool = aix.Tool(
    integration="aixplain/mcp-server",
    name="Remote MCP Tool",
    config={"url": "https://remote.mcpservers.org/fetch/mcp"},
)
mcp_tool.save()
mcp_tool.allowed_actions = ["fetch"]

# Agent
mcp_agent = aix.Agent(
    name="Remote MCP Demo Agent",
    description="Fetches a URL and summarises.",
    instructions="Use the MCP tool to fetch content, then summarise in 5 concise bullets.",
    tools=[mcp_tool],
)

# Run
response = mcp_agent.run(query="Summarise https://aixplain.com")
print(response.data.output)
Show output

Troubleshooting​

Agent doesn't invoke the tool Make the instructions explicit: tell the agent to use the MCP tool by name for the relevant task.

Connection or timeout errors Check the MCP server URL, network egress rules, and any firewall restrictions on the server side.

Too many parameters / agent ignores some actions Overexposed actions inflate parameter count. Tighten allowed_actions to only what you need.

Invalid action name Confirm action identifiers with mcp_tool.list_actions().

Tool not found Ensure mcp_tool.save() was called after creation.

What's next​