Data Access (MCP)

Query workspace data through the Model Context Protocol using SQL tools compatible with any MCP client.

Two other surfaces cover most use cases. For agent data access inside conversations, use platform functions, which provide the same query capabilities plus Python UDFs and AI operations. For an MCP endpoint built into the Platform API itself (world-model tools, Platform API credentials), use the MCP Server at /v1/mcp. This page documents Data-MCP, a separate standalone service that authenticates with Classic API credentials.

Data-MCP is an MCP (Model Context Protocol) server that provides SQL query access to your workspace's data tables. It works with any MCP-compatible client.

Background reading. For context on how workspace data is structured, see the World Model conceptual docs.

Authentication

Data-MCP authenticates with Classic API credentials. Every request requires the X-Org-Id header identifying your organization, plus one of two credential modes.

Pre-exchanged token - you have already exchanged your API key for a token:

Header	Value
Authorization	Bearer <token>
X-Org-Id	Your organization ID

Credential pass-through - Data-MCP performs the token exchange on your behalf:

Header	Value
X-Api-Key	Your Classic API key
X-Api-Key-Id	The API key ID
X-User-Id	The user the key belongs to
X-Org-Id	Your organization ID

Requests without X-Org-Id return 400. Requests that provide neither a bearer token nor the full credential header set return 401. See Authentication for the Classic API credential flow.

Backend URL Override (optional)

For multi-region deployments, the MCP server accepts an optional X-Amigo-Api-Url header that selects which Classic API deployment serves the query. The value must match a host on the server's allowlist, which always includes the deployment's configured default. Unknown hosts return 400. Requests without the header use the default backend.

Header	Value
X-Amigo-Api-Url	Target Classic API host (e.g. https://api.amigo.ai)

Available Tools

The MCP server exposes seven tools for exploring and querying workspace data.

sql_query

Execute read-only SELECT queries against workspace tables. Results are limited to 1,000 rows with a 30-second timeout.

describe_query

Returns the schema of a query result without executing it. Useful for understanding what columns a query will return before running it.

tables

List available tables in the workspace schema. Supports an optional name filter to narrow results.

table_schema

Returns column names and data types for a specific table.

sample_data

Preview the first N rows of a table. Helpful for understanding data shape before writing queries.

table_detail

Extended table metadata including properties, statistics, and partitioning information.

profile_column

Statistical profile of a specific column. Returns min, max, null count, distinct count, and value distribution.

Connection

Data-MCP uses the MCP Streamable HTTP transport. The endpoint is stateless: no session affinity is required, and it works behind standard load balancers.

Property	Value
Endpoint	https://api.platform.amigo.ai/data-mcp/mcp
Transport	Streamable HTTP
Protocol	JSON-RPC 2.0

The service is mounted at /data-mcp; the streamable-HTTP transport endpoint that clients connect to lives at /data-mcp/mcp under that mount, which is why the URL has the doubled segment.

Regional endpoints are also available, so queries execute within the same region as the workspace data. See Regions & Endpoints for the full list of regional base URLs.

Example

List available tables using a JSON-RPC request:

curl -X POST https://api.platform.amigo.ai/data-mcp/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "tables",
      "arguments": {}
    },
    "id": 1
  }'

Data Isolation

Queries are scoped to the authenticated organization. There is no way to query another organization's data, even with valid credentials for a different organization. The X-Org-Id header and the presented credentials must belong to the same organization.