Skip to main content
Beta: This feature is in beta. The API schema may change as we iterate on the design.
MCP (Model Context Protocol) 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
  2. Datagrid auto-syncs tools on create
  3. Attach MCP servers to an agent via Create agent or Update agent using the mcp_servers field
  4. Call converse with agent_id

​
End-to-End Example

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)

​
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. 
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"
            }
        }
    }
)

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

​
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 Agent MCP mappings