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:

Protocol	URL pattern	Best for
HTTP	http://host:port/mcp	Stateless tools — fetch, search, retrieval
SSE	http://host:port/sse	Streaming 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

note

# replaces: manual MCP client setup + tool registration + session management
# aixplain hosts 900+ MCP endpoints; one API key, no server config

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.