> ## 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.
# Create MCP server
> Register a new MCP server in the current teamspace. Each teamspace can have at most 30 registered MCP servers.
Registers a new MCP server at teamspace scope.
Use this first in the MCP setup flow.
Datagrid automatically attempts an initial tool sync after create.
Each teamspace can register up to **30 MCP servers**. If the limit is reached, the request returns `409 Conflict`. Remove an existing server before adding a new one.
You can provide auth in either form:
* `authorization_secret_id`: reference an existing Datagrid secret
* `authorization`: raw Authorization header value (Datagrid stores it as a secret automatically)
If both are sent, `authorization` takes precedence.
Ownership note:
* `authorization` creates a Datagrid-managed secret for this MCP server. If you later rotate or clear that value, Datagrid cleans up the previously auto-created secret.
* `authorization_secret_id` references an existing secret that you manage. Datagrid uses the reference, but does not delete that secret automatically.
```bash theme={null}
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": "manhour",
"base_url": "https://mcp.example.com/mcp",
"transport": "http",
"authorization": "Bearer external-api-token"
}'
```
```python Python SDK theme={null}
server = client.organization.mcp_servers.create(
name="manhour",
base_url="https://mcp.example.com/mcp",
transport="http",
authorization="Bearer external-api-token",
)
```
```typescript TypeScript SDK theme={null}
const server = await client.organization.mcpServers.create({
name: "manhour",
base_url: "https://mcp.example.com/mcp",
transport: "http",
authorization: "Bearer external-api-token",
});
```
## OpenAPI
````yaml post /organization/mcp-servers
openapi: 3.0.3
info:
version: 0.1.1
title: Datagrid API
description: Datagrid API
servers:
- url: https://api.datagrid.com/v1
security:
- BearerAuth: []
paths:
/organization/mcp-servers:
post:
tags:
- MCP Servers
summary: Create MCP server
description: >-
Register a new MCP server in the current teamspace. Each teamspace can
have at most 30 registered MCP servers.
operationId: CreateMcpServer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMcpServerRequest'
responses:
'201':
description: Created MCP server
content:
application/json:
schema:
$ref: '#/components/schemas/McpServer'
'409':
description: >-
Conflict. Either an MCP server with the same URL is already
registered, or the teamspace has reached the maximum number of
registered MCP servers (30).
'429':
description: >-
Rate limit exceeded. The request has been throttled because the rate
limit for this endpoint has been reached. Check the `Retry-After`
response header and retry after the specified number of seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
x-codeSamples:
- lang: JavaScript
source: |-
import Datagrid from 'datagrid-ai';
const client = new Datagrid({
apiKey: process.env['DATAGRID_API_KEY'], // This is the default and can be omitted
});
const mcpServer = await client.organization.mcpServers.create({
base_url: 'https://example.com',
name: 'name',
});
console.log(mcpServer.id);
- lang: Python
source: |-
import os
from datagrid_ai import Datagrid
client = Datagrid(
api_key=os.environ.get("DATAGRID_API_KEY"), # This is the default and can be omitted
)
mcp_server = client.organization.mcp_servers.create(
base_url="https://example.com",
name="name",
)
print(mcp_server.id)
components:
schemas:
CreateMcpServerRequest:
type: object
required:
- name
- base_url
properties:
name:
type: string
maxLength: 255
base_url:
type: string
format: uri
description: The HTTPS URL of the MCP server.
transport:
type: string
default: http
enum:
- http
nullable: true
maxLength: 64
icon_url:
type: string
nullable: true
maxLength: 1024
protocol_version:
type: string
nullable: true
maxLength: 32
authorization_secret_id:
type: string
nullable: true
description: >-
Secret ID containing the full Authorization header value to use when
calling this MCP server.
authorization:
type: string
nullable: true
maxLength: 64000
description: >-
Raw Authorization header value (for example, 'Bearer ').
Datagrid stores it as a secret and links it to this server. If both
authorization and authorization_secret_id are provided,
authorization takes precedence.
McpServer:
type: object
required:
- object
- id
- name
- icon_url
- base_url
- transport
- protocol_version
- authorization_secret_id
- status
- metadata
- created_at
- updated_at
properties:
object:
type: string
enum:
- mcp_server
id:
type: string
name:
type: string
icon_url:
type: string
nullable: true
base_url:
type: string
format: uri
transport:
type: string
protocol_version:
type: string
nullable: true
authorization_secret_id:
type: string
nullable: true
description: >-
Secret ID containing the full Authorization header value used for
this registered MCP server.
status:
type: string
metadata:
$ref: '#/components/schemas/McpServerMetadata'
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
RateLimitError:
type: object
description: >-
Returned when the rate limit is exceeded. Rate limits are enforced per
teamspace, endpoint path, and HTTP method over a 60-second sliding
window. Each endpoint may have its own limit — check the
X-RateLimit-Limit response header for the effective value.
required:
- error
- message
- retryable
- status_code
properties:
status_code:
type: integer
description: The HTTP status code (429).
statusCode:
type: integer
deprecated: true
description: Deprecated. Use status_code instead.
error:
type: string
enum:
- rate_limit_exceeded
description: The error code identifying this as a rate limit error.
message:
type: string
description: A human-readable error message.
mitigation:
type: string
description: Suggested action to resolve the error.
retryable:
type: boolean
description: Whether the request can be retried after a delay.
details:
type: object
properties:
reason:
type: string
description: A detailed explanation of why the rate limit was exceeded.
McpServerMetadata:
type: object
additionalProperties: true
description: Safe subset of server metadata exposed to API consumers.
properties:
requires_oauth:
type: boolean
oauth_configured:
type: boolean
tool_count:
type: integer
last_synced_at:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
````