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

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

## 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](/api-reference/mcp-servers/create-mcp-server)
2. Datagrid auto-syncs tools on create
3. Attach MCP servers to an agent via [Create agent](/api-reference/agents/create-agent) or [Update agent](/api-reference/agents/update-agent) using the `mcp_servers` field
4. Call `converse` with `agent_id`

## End-to-End Example

<CodeGroup>
  ```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"
    }'
  ```
</CodeGroup>

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

<CodeGroup>
  ```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"
          }
        }
      }
    }'
  ```
</CodeGroup>

## 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](/api-reference/mcp-servers/create-mcp-server)
* [Retrieve MCP server](/api-reference/mcp-servers/retrieve-mcp-server)
* [List MCP servers](/api-reference/mcp-servers/list-mcp-servers)
* [Update MCP server](/api-reference/mcp-servers/update-mcp-server)
* [Delete MCP server](/api-reference/mcp-servers/delete-mcp-server)

**Agent MCP mappings**

* Use `mcp_servers` in [Create agent](/api-reference/agents/create-agent) or [Update agent](/api-reference/agents/update-agent)