> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate MCP

> Attach Model Context Protocol servers to extend your agent with external tools.

MCP is an open standard for securely connecting AI assistants to external data sources and tools. In Zero Runtime AI Agents, attach MCP servers to auto-discover services, databases, and APIs. The agent picks and runs the right tools and turns results into natural responses.

## How It Works

MCP tools are automatically discovered and made available to your agent, which intelligently chooses which tools to use based on user requests. When a user asks for information that requires external data, the agent will:

<Steps>
  <Step title="Identify the need">
    Detect that the user's request requires external data.
  </Step>

  <Step title="Select tools">
    Choose the appropriate tools from the available MCP servers.
  </Step>

  <Step title="Execute">
    Run the tools with the relevant parameters.
  </Step>

  <Step title="Respond">
    Process the results and provide a natural language response.
  </Step>
</Steps>

This integration allows your voice agent to access real-time data and external services while maintaining a natural conversational flow.

## Transport Methods

Zero Runtime supports two transport methods for MCP servers.

| Transport                         | Communication                                          | Best For                                             |
| :-------------------------------- | :----------------------------------------------------- | :--------------------------------------------------- |
| **STDIO**                         | Direct process communication with local Python scripts | Custom tools and functions, server-side integrations |
| **HTTP** (Streamable HTTP or SSE) | Network-based communication with external MCP services | Third-party integrations, remote MCP servers         |

## Example

Pass MCP servers to the agent via the `mcp_servers` parameter. Use `MCPServerStdio` for local scripts and `MCPServerHTTP` for remote services.

<CodeGroup>
  ```python title="Python" Python theme={null}
  import sys
  from zeroruntime import Agent, MCPServerStdio, MCPServerHTTP

  class MyVoiceAgent(Agent):
      def __init__(self, pipeline):
          super().__init__(
              agent_id="assistant",
              instructions="You are a helpful assistant with access to real-time data.",
              pipeline=pipeline,
              mcp_servers=[
                  # STDIO - local script
                  MCPServerStdio(
                      executable_path=sys.executable,
                      process_arguments=["mcp_stdio_example.py"],
                  ),
                  # HTTP - remote service
                  MCPServerHTTP(
                      endpoint_url="https://your-mcp-service.com/api/mcp",
                      request_headers={"Authorization": "Bearer <token>"},
                  ),
              ],
          )
  ```

  ```typescript title="Node JS" Node JS theme={null}
  import { Agent, MCPServerStdio, MCPServerHTTP } from '@zeroruntime/js-sdk';

  class MyVoiceAgent extends Agent {
    constructor(pipeline) {
      super({
        agent_id: 'assistant',
        instructions: 'You are a helpful assistant with access to real-time data.',
        pipeline,
        mcp_servers: [
          // STDIO - local script
          MCPServerStdio({
            executable_path: 'python3',
            process_arguments: ['mcp_stdio_example.py'],
          }),
          // HTTP - remote service
          MCPServerHTTP({
            endpoint_url: 'https://your-mcp-service.com/api/mcp',
            request_headers: { Authorization: 'Bearer <token>' },
          }),
        ],
      });
    }
  }
  ```
</CodeGroup>

The agent auto-discovers every tool exposed by each server and chooses among them at
runtime, so you don't register tools individually.

## Server options

### `MCPServerStdio` (local process)

| Parameter           | Type                     | Default    | Description                                                                                                                                     |
| :------------------ | :----------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `executable_path`   | `str`                    | *required* | Program to run (e.g. `sys.executable` for Python).                                                                                              |
| `process_arguments` | `list[str]`              | `[]`       | Its arguments -- typically the server script.                                                                                                   |
| `environment_vars`  | `dict[str, str] \| None` | `None`     | Environment for the child. `None` inherits this process's, which is usually what you want: the server needs the same API keys you already have. |
| `working_directory` | `str \| Path \| None`    | `None`     | Directory to run it in.                                                                                                                         |
| `session_timeout`   | `float`                  | `5.0`      | Seconds to wait for the connection and for each tool call. 5 is tight for a server that starts an interpreter; pass `30` for those.             |

### `MCPServerHTTP` (remote service)

| Parameter             | Type                     | Default    | Description                                                                                                       |
| :-------------------- | :----------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------- |
| `endpoint_url`        | `str`                    | *required* | The server's URL.                                                                                                 |
| `request_headers`     | `dict[str, str] \| None` | `None`     | Sent with every request -- an API key usually lives here. Read in this process, so the credential stays with you. |
| `connection_timeout`  | `float`                  | `10.0`     | Seconds to wait for the connection.                                                                               |
| `stream_read_timeout` | `float`                  | `300.0`    | Seconds a quiet stream may stay open. Long by default: an MCP server that has nothing to say is not broken.       |
| `session_timeout`     | `float`                  | `5.0`      | Seconds to wait for the session, and for each tool call.                                                          |

## What's Next

<CardGroup cols={2}>
  <Card title="Function Tools" icon="wrench" href="/build/tools-and-capabilities/function-tools">
    Add custom Python functions as tools.
  </Card>

  <Card title="RAG" icon="database" href="/build/tools-and-capabilities/rag">
    Ground responses in a knowledge base.
  </Card>
</CardGroup>

## References

<Tabs>
  <Tab title="Python">
    #### Examples

    <CardGroup cols={2}>
      <Card title="MCP Client" icon="github" href="https://github.com/ZeroRuntimeAI/zeroruntime-python-examples/blob/main/tools/mcp_example.py">
        Consume tools from an MCP server.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Node JS">
    #### Examples

    <CardGroup cols={2}>
      <Card title="MCP Client" icon="github" href="https://github.com/ZeroRuntimeAI/zeroruntime-js-examples/blob/main/tools/mcp_example.ts">
        Consume tools from an MCP server.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>