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

# MCP Servers (Beta)

> Connect external tools to your agent using the Model Context Protocol.

<Note>
  **Beta**: This feature is in beta. The API schema may change as we iterate on the design.
</Note>

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) is an open standard that enables AI agents to interact with external tools and services. By passing MCP server configurations in your converse requests, you can extend the agent's capabilities with custom tools.

MCP servers are configured per-request. The agent will discover available tools from each server and use them as needed to complete the user's request.

## Basic Usage

<CodeGroup>
  ```python Python theme={null}
  import os
  from datagrid_ai import Datagrid

  client = Datagrid(api_key=os.environ.get("DATAGRID_API_KEY"))

  response = client.converse(
      prompt="Tell me about my projects",
      config={
          "mcp_servers": [
              {
                  "type": "inline_mcp",
                  "server_label": "project-api",
                  "server_url": "https://mcp.mycompany.com",
                  "server_description": "Project management API",
                  "authorization": "Bearer your-api-token"
              }
          ]
      }
  )

  print(response.content[0].text)
  ```

  ```javascript JavaScript theme={null}
  import Datagrid from 'datagrid-ai';

  const client = new Datagrid({
    apiKey: process.env['DATAGRID_API_KEY']
  });

  const response = await client.converse({
    prompt: 'Tell me about my projects',
    config: {
      mcp_servers: [
        {
          type: 'inline_mcp',
          server_label: 'project-api',
          server_url: 'https://mcp.mycompany.com',
          server_description: 'Project management API',
          authorization: 'Bearer your-api-token'
        }
      ]
    }
  });

  console.log(response.content[0].text);
  ```

  ```bash curl theme={null}
  curl -X POST https://api.datagrid.com/v1/converse \
    -H "Authorization: Bearer $DATAGRID_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Tell me about my projects",
      "config": {
        "mcp_servers": [{
          "type": "inline_mcp",
          "server_label": "project-api",
          "server_url": "https://mcp.mycompany.com",
          "server_description": "Project management API",
          "authorization": "Bearer your-api-token"
        }]
      }
    }'
  ```
</CodeGroup>

## Configuration Options

| Field                | Type   | Required | Description                                                                                   |
| -------------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `type`               | string | Yes      | Must be `"inline_mcp"` for server configs passed in the request                               |
| `server_label`       | string | Yes      | Unique identifier for the server (max 64 characters). Used for tool namespacing.              |
| `server_url`         | string | Yes      | HTTPS URL of the MCP streamable HTTP endpoint                                                 |
| `server_description` | string | No       | Description of what the server provides (max 500 characters)                                  |
| `authorization`      | string | No       | Value sent in the `Authorization` header when calling the MCP server (e.g., `"Bearer token"`) |

## Multiple Servers

You can connect multiple MCP servers in a single request. Each server's tools will be available to the agent:

<CodeGroup>
  ```python Python theme={null}
  response = client.converse(
      prompt="Get the weather forecast and add it to my calendar",
      config={
          "mcp_servers": [
              {
                  "type": "inline_mcp",
                  "server_label": "weather",
                  "server_url": "https://mcp.example.com/weather",
                  "authorization": "Bearer weather-token"
              },
              {
                  "type": "inline_mcp",
                  "server_label": "calendar",
                  "server_url": "https://mcp.example.com/calendar",
                  "authorization": "Bearer calendar-token"
              }
          ]
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await client.converse({
    prompt: 'Get the weather forecast and add it to my calendar',
    config: {
      mcp_servers: [
        {
          type: 'inline_mcp',
          server_label: 'weather',
          server_url: 'https://mcp.example.com/weather',
          authorization: 'Bearer weather-token'
        },
        {
          type: 'inline_mcp',
          server_label: 'calendar',
          server_url: 'https://mcp.example.com/calendar',
          authorization: 'Bearer calendar-token'
        }
      ]
    }
  });
  ```
</CodeGroup>

## How It Works

When you pass an MCP server in a converse request, Datagrid handles the full [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle) automatically:

1. **Initialization**: Datagrid sends `initialize` to negotiate protocol version and capabilities, then confirms with `notifications/initialized`
2. **Tool Discovery**: Datagrid calls `tools/list` to discover available tools, with `MCP-Session-Id` and `MCP-Protocol-Version` headers
3. **Tool Execution**: When the agent decides to use a tool, Datagrid calls `tools/call` with the appropriate parameters and session headers
4. **Session Recovery**: If a session expires, Datagrid automatically re-initializes and retries the request
5. **Credential Isolation**: Authorization values are scoped per server and never shared between servers

References:

* [MCP Lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle)
* [MCP Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)

## Security

* **HTTPS Required**: All MCP server URLs must use HTTPS
* **SSRF Protection**: Requests to private IP addresses, localhost, and internal domains are blocked
* **Credential Isolation**: Authorization tokens are isolated per-server and never shared between servers
* **Ephemeral**: Server configurations are not persisted - they only exist for the duration of the request

## Building MCP Servers

To create an MCP server compatible with Datagrid, implement the [Model Context Protocol specification](https://modelcontextprotocol.io/specification) using [streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports). Your server must handle the following methods:

* `initialize` - Negotiates protocol version and capabilities. Return `MCP-Session-Id` in the response header.
* `notifications/initialized` - Accepts the initialization completion notification
* `tools/list` - Returns available tools and their [JSON Schema](https://json-schema.org/) definitions
* `tools/call` - Executes a tool and returns the result

All requests after `initialize` will include `MCP-Session-Id` and `MCP-Protocol-Version` headers.

<Tip>
  Frameworks like [FastMCP](https://github.com/jlowin/fastmcp) and the [official MCP SDK](https://modelcontextprotocol.io/docs/develop/build-server) handle `initialize`, session management, and transport automatically. See [Build an MCP Server](https://modelcontextprotocol.io/docs/develop/build-server) to get started.
</Tip>