> ## 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.

# Overview

> Register and manage MCP servers at teamspace scope for use in converse.

> [!NOTE]
>
> **Beta**: This feature is in beta. The API schema may change as we iterate on the design.

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) is an open standard that enables AI agents to interact with external tools and services.

Datagrid supports **registered MCP servers**: teamspace-level server registration with automatic tool sync and per-agent mapping.

## What This API Manages

* Teamspace-level MCP server registry
* Tool metadata sync from each MCP server
* Per-agent MCP server mappings
* Auth configuration for registered servers (`authorization` or `authorization_secret_id`) and optional per-agent overrides (`credential_id`)

After mapping a server to an agent, its MCP tools become available in `converse` for that agent.

If your MCP server is behind a firewall, allowlist the [Agent Server egress IPs](https://developers.datagrid.com/introduction/agent-server-egress-ips.md).

## Secret Ownership

* Use `authorization` when you want Datagrid to persist the raw Authorization header for this MCP server. Datagrid stores it as a secret and treats that secret as MCP-server-managed.
* Use `authorization_secret_id` when you already have a Datagrid secret and want the MCP server to reference it. That secret remains caller-managed.
* When auth is rotated or cleared, Datagrid only auto-deletes secrets that it created from `authorization`.

## Provisioning Flow

1. [Create MCP server](https://developers.datagrid.com/api-reference/mcp-servers/create-mcp-server.md)
2. Datagrid auto-syncs tools on create
3. Attach MCP servers to an agent via [Create agent](https://developers.datagrid.com/api-reference/agents/create-agent.md) or [Update agent](https://developers.datagrid.com/api-reference/agents/update-agent.md) using the `mcp_servers` field
4. Call `converse` with `agent_id`

## End-to-End Example

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

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

# 1) Register server
server = client.organization.mcp_servers.create(
    name="project-api",
    base_url="https://mcp.mycompany.com/mcp"
)

# 2) Create agent with MCP servers attached inline
agent = client.agents.create(
    name="My Agent",
    mcp_servers=[{"server_id": server.id}]
)

# 3) Run conversation
response = client.converse(
    prompt="Use project tools and summarize next actions",
    agent_id=agent.id
)

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

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

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

// 1) Register server
const server = await client.organization.mcpServers.create({
  name: 'project-api',
  base_url: 'https://mcp.mycompany.com/mcp'
});

// 2) Create agent with MCP servers attached inline
const agent = await client.agents.create({
  name: 'My Agent',
  mcp_servers: [{ server_id: server.id }]
});

// 3) Run conversation
const response = await client.converse({
  prompt: 'Use project tools and summarize next actions',
  agent_id: agent.id
});

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

```bash curl theme={null}
# 1) Register server
curl -X POST https://api.datagrid.com/v1/organization/mcp-servers \
  -H "Authorization: Bearer $DATAGRID_API_KEY" \
  -H "Datagrid-Teamspace: $DATAGRID_TEAMSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-api",
    "base_url": "https://mcp.mycompany.com/mcp"
  }'

# 2) Create agent with MCP servers attached inline
curl -X POST https://api.datagrid.com/v1/agents \
  -H "Authorization: Bearer $DATAGRID_API_KEY" \
  -H "Datagrid-Teamspace: $DATAGRID_TEAMSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "mcp_servers": [
      { "server_id": "SERVER_ID" }
    ]
  }'

# 3) Run conversation
curl -X POST https://api.datagrid.com/v1/converse \
  -H "Authorization: Bearer $DATAGRID_API_KEY" \
  -H "Datagrid-Teamspace: $DATAGRID_TEAMSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "prompt": "Use project tools and summarize next actions"
  }'
```

## Per-Request Credentials

Use `config.mcp_credentials` in the converse request to pass per-request credentials for registered MCP servers. This is useful when different users have their own tokens for the same server.

Keys are registered MCP server IDs. Provide either `authorization` (a raw Authorization header value) or `credential_id` (a reference to a stored credential). If both are present, `authorization` takes precedence.

```python Python theme={null}
response = client.converse(
    prompt="Get my project status",
    agent_id="AGENT_ID",
    config={
        "mcp_credentials": {
            "server-id-1": {
                "authorization": "Bearer user-specific-token"
            },
            "server-id-2": {
                "credential_id": "stored-credential-id"
            }
        }
    }
)
```

```javascript JavaScript theme={null}
const response = await client.converse({
  prompt: 'Get my project status',
  agent_id: 'AGENT_ID',
  config: {
    mcp_credentials: {
      'server-id-1': {
        authorization: 'Bearer user-specific-token'
      },
      'server-id-2': {
        credential_id: 'stored-credential-id'
      }
    }
  }
});
```

```bash curl theme={null}
curl -X POST https://api.datagrid.com/v1/converse \
  -H "Authorization: Bearer $DATAGRID_API_KEY" \
  -H "Datagrid-Teamspace: $DATAGRID_TEAMSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "prompt": "Get my project status",
    "config": {
      "mcp_credentials": {
        "server-id-1": {
          "authorization": "Bearer user-specific-token"
        },
        "server-id-2": {
          "credential_id": "stored-credential-id"
        }
      }
    }
  }'
```

## Authentication Priority

When resolving auth for an MCP server at converse time, Datagrid uses the first available source:

1. **Per-request `authorization`** (highest)
2. **Per-request `credential_id`**
3. Agent mapping `credential_id`
4. Server `authorization_secret_id`
5. Server OAuth token
6. No auth

## Runtime Lifecycle

When MCP tools are available for a turn, Datagrid handles MCP lifecycle operations automatically:

1. **Initialization**: `initialize` then `notifications/initialized`
2. **Tool discovery**: `tools/list`
3. **Tool execution**: `tools/call`
4. **Session recovery**: automatic re-initialize/retry when sessions expire

All requests after initialization include `MCP-Session-Id` and `MCP-Protocol-Version`.

## Limits

* Each teamspace can register a maximum of **30 MCP servers**. Attempting to create a server beyond this limit returns a `409 Conflict` error. Remove an existing server before adding a new one.

## Security

* MCP server URLs must be HTTPS
* SSRF protection: private IPs, localhost, and internal domains are blocked
* Teamspace isolation is enforced for server and credential references
* Authorization values are isolated per server and never shared across servers
* Per-request credentials are not persisted; scoped to the individual request

## Local Development

For local MCP development, expose your local server through an HTTPS tunnel (e.g. ngrok or cloudflared), then register that URL as the `base_url`.

## Endpoints

**MCP Servers**

* [Create MCP server](https://developers.datagrid.com/api-reference/mcp-servers/create-mcp-server.md)
* [Retrieve MCP server](https://developers.datagrid.com/api-reference/mcp-servers/retrieve-mcp-server.md)
* [List MCP servers](https://developers.datagrid.com/api-reference/mcp-servers/list-mcp-servers.md)
* [Update MCP server](https://developers.datagrid.com/api-reference/mcp-servers/update-mcp-server.md)
* [Delete MCP server](https://developers.datagrid.com/api-reference/mcp-servers/delete-mcp-server.md)

**Agent MCP mappings**

* Use `mcp_servers` in [Create agent](https://developers.datagrid.com/api-reference/agents/create-agent.md) or [Update agent](https://developers.datagrid.com/api-reference/agents/update-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.