MCP servers
An MCP server is a chosen set of a project's tools, each exposed as one MCP tool to clients such as Claude, ChatGPT or Cursor. Credentials stay in the project's secrets: the client holds none.
A project holds any number of servers, on every plan. Managing one needs the
member role.
See the OpenAPI spec, or browse it under API Reference → MCP Servers.
Data Model
MCP server
| Field | Type | Description |
|---|---|---|
id | string | Public MCP server ID (mcps_ prefix). |
project_id | string | The owning project. |
url | string | Where MCP clients connect (Streamable HTTP). An oauth server answers 401 without a token, naming its OAuth protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource/servers/{id} on the same host, which names the issuer to sign in at. |
name | string | serverInfo.name. |
title | string, nullable | serverInfo.title. |
instructions | string, nullable | instructions in the initialize result. |
logo | string, nullable | serverInfo.icons; an https URL. |
website_url | string, nullable | serverInfo.websiteUrl. |
tools | object[] | tool_id, action, and the name and description clients see; at most 100. |
tool_mode | list | compact | list lists every tool; compact serves search, describe and call over them. |
context_keys | string[] | The keys of the stored context; values are never returned. |
auth | object | Who may connect. See Auth. |
daily_call_limit | integer, nullable | Calls per UTC day. Required when auth is none. |
created_at | string (date-time) | |
updated_at | string (date-time) | |
unavailable_tools | object[] | Items the server does not serve now: the tool is gone, or the action is no longer one of its available actions. tools/list leaves them out and a call to one is a tool error. Returned by get, create and update, not by list. |
Key
For a server whose auth.type is header.
| Field | Type | Description |
|---|---|---|
id | string | Public key ID (mcpk_ prefix). |
project_id | string | The owning project. |
mcp_server_id | string | The server the key opens. |
name | string, nullable | Label. |
key_prefix | string | The start of the key, to tell keys apart. |
context_keys | string[] | The keys of the stored context; values are never returned. |
created_at | string (date-time) | |
key | string | The key (nat_mcp_ prefix), returned only by the create response. |
Key Concepts
Tools and actions
Each (tool_id, action) pair is one MCP tool. action is required when the
tool declares actions (a builtin or mcp tool) and must be one of them;
on any other tool it is ignored. To expose three actions of one tool, list it
three times. A tool the project cannot read is 400. A tool the writer may
not call is 403: a narrowed key
needs tools:CallTool, and a template is held to its
deployer's authority.
Each item's name is its name, else its action, else the tool's name; two
items resolving to one name are 400. Its input schema is the action's (a
builtin tool's operation), or the tool's parameters, without the keys
preset_parameters pins. An action of an external mcp tool takes the
schema its server lists, as
GET /v1/projects/{project_id}/tools/{tool_id}/actions
answers it; when that listing fails or names no such action, it takes any
object.
Input and output mapping stay on the tool (preset_parameters,
output_mapping), so a tool behaves the same in an agent and in a server. A
server item changes only what the client sees.
To narrow what clients send to a tool, serve a pipeline over it
(narrowing a builtin tool).
Context
context is merged into the tool_context of every call the server makes, so
a tool reads it as {{context:<key>}}. Three layers; on a key set twice the
platform wins over the caller, the caller over the server:
| Layer | Set on |
|---|---|
| Server | context on the server |
| Caller | context on an allowlist entry or a header key; a tenant issuer's context_claims |
| Platform | naturali_mcp_server_id; for an OAuth caller naturali_caller_id, naturali_caller_issuer, naturali_caller_email |
For an OAuth caller, naturali_caller_issuer and naturali_caller_id are the
token's issuer and subject: the server's own naturali issuer
(https://mcp.naturali.ai/servers/{id}) and the naturali account id, or
auth.issuer and the token's sub. naturali_caller_email is set only for a
verified email: the account's, or the token's email claim unless
email_verified is false. All three layers travel with the call's
credential, so they also reach every tool the call starts (a builtin item's
own calls and a call-tool relay), and a tool_context key that work sends
never replaces one of them.
Keys are header names; naturali_* is refused. Values are literal strings: a
credential belongs in the tool's headers as a {{secret:…}}. A tool whose
definition reads {{context:naturali_caller_…}} is refused unless
auth.type is oauth.
Auth
One type per server; a server that needs two is two servers.
auth | Who connects |
|---|---|
{ "type": "oauth", "mode": "members" } | Project members, by naturali login |
{ "type": "oauth", "mode": "allowlist", "allowlist": [...] } | The listed emails, verified, each with optional context, by naturali login |
{ "type": "oauth", "issuer": "...", "jwks_uri": "..." } | Whoever the tenant's authorization server issues a token to |
{ "type": "header", "header_name": "..." } | Holders of a key of this server; header_name defaults to Authorization (Bearer <key>) |
{ "type": "none" } | Anyone |
Changing auth.type away from header deletes the server's keys; changing
auth away from naturali login disconnects every client signed in by it.
OAuth
An oauth server answers 401 without a valid token, with
WWW-Authenticate: Bearer resource_metadata="https://mcp.naturali.ai/.well-known/oauth-protected-resource/servers/{id}".
That document (RFC 9728) names the issuer the client signs in at:
-
naturali login (no
issuer): the server's own issuer,https://mcp.naturali.ai/servers/{id}, with dynamic client registration and PKCE. The person signs in to naturali and approves the client for this server only; the token reaches this server and nothing else. Membership and the allowlist are checked on every request. Approved clients are listed, and disconnected, with the account's other connected apps. -
The tenant's issuer:
issuer,jwks_uri(https), optionalscopesandcontext_claims. naturali checks every token: the signature by a key ofjwks_uri(RS256,ES256orEdDSA),issequal toissuer,exp,nbf,audnaming the server'surl, and every one ofscopesin itsscope(orscp) claim. The token is never forwarded to a tool.context_claimsmaps atool_contextkey to the claim whose string value it takes, so per-caller context comes from the tenant's directory.MCP clients expect the authorization server to support dynamic client registration (or client ID metadata documents) and the
resourceparameter (RFC 8707), and to issue tokens whoseaudis the server'surl.
Connect a signed-in person's account to their actor serves a per-person tool this way.
{
"type": "oauth",
"issuer": "https://login.acme.com",
"jwks_uri": "https://login.acme.com/.well-known/jwks.json",
"scopes": ["mcp"],
"context_claims": { "client_id": "acme_client" }
}
Serving
tools/list resolves every item against its tool on each request. An item
whose tool is gone, or whose action the tool does not offer, is left out and
listed in unavailable_tools; calling it, or any name the server does not
serve, is a tool error. Each call is
POST /v1/projects/{project_id}/tools/{tool_id}/call
with the item's action and the merged context, paid for by the project's
billing owner and gated like any direct call.
A caller acts under the server's bound, never the project's full access:
tools:CallTool on the server's tools, plus what each builtin
item performs, on the resource its preset_parameters pin (a coach's
agent_id) or on any resource of that type when none is pinned:
| Item | Adds to the bound |
|---|---|
| An action | Each IAM action it performs, on the resource of the action's own type its presets pin, with what the runtime asks to serve it, as a key holding the action carries it (Capabilities). |
list-memories | memories:ListMemories also on the preset memory_store_id's store. |
search-knowledge | embeddings:CreateEmbeddings, for the query's embedding; knowledge:SearchKnowledge on memories and on each store the preset memory_store_ids lists (any store when none), so the search reads memories as well as documents. |
A {{context:<key>}} preset | The pin resolved from the caller's context, so an OAuth caller with x_case in its context reaches that case and no other. |
call-tool | tools:CallTool on the preset tool_id, what that target performs, and actors:GetActor on the actor_id the call names. |
A tool with execute.auth.type: oauth_connection | oauth-connections:UseOauthConnection, served or the target of a call-tool. |
An item whose pin cannot be resolved (a context key the caller lacks) is still
listed; calling it is a tool error naming the key, and every other item works.
Nothing else is allowed, so whatever the tool reaches on the caller's behalf (a
{ "type": "document" } or { "type": "tool_output" } message) is refused
403 unless the bound allows it, and the generation never starts. The bound holds on this API's own routes too: the runtime decides each
one it knows, and any other is refused. An agent the server runs that must act
on its own (a builtin or naturali action) needs run_as: agent, so its
policy_ids grant what the caller's bound does not
(Execution identity).
Limits
| Limit | Counts | Over it |
|---|---|---|
daily_call_limit, per UTC day | Tool calls by every caller: tools/call, or call on a compact server | 429 QUOTA_EXCEEDED with meta.window: day, Retry-After until midnight UTC |
| 600 requests per minute, on every server | Every request a caller is let in for, tools/list included | 429 QUOTA_EXCEEDED with meta.window: minute, Retry-After until the minute turns |
Both answer at the server's url before any tool runs. A refused request is
not counted against the day.
Usage
Each call is logged per UTC day, caller and item: count and how many of them
failures, never the arguments. The caller is a key (its mcpk_ ID) on a
header server, an account (the naturali account ID) on an oauth server by
naturali login, a subject (the token's sub) on one with auth.issuer, and
anonymous on a none one. Read the log with
GET /v1/projects/{project_id}/mcp-servers/{mcp_server_id}/usage,
newest day first.
Formations
A server is declarable as an mcp_server resource in a
formation template, so the tools a stack exposes to MCP
clients are deployed with the tools themselves. Its properties are
McpServerResourceProperties in the formations spec:
the fields
POST /v1/projects/{project_id}/mcp-servers
takes. Each declares the whole value: dropping title from the template clears
it.
resources:
Narrator:
type: tool
properties:
name: generate-narration-audio
type: http
execute:
url: https://example.com/tts
Narration:
type: mcp_server
properties:
name: narration
tools:
- tool_id:
ref: Narrator
- tool_id: tool_V1d30R3nd3r
action: render
auth:
type: oauth
mode: members
tool_id takes a {ref} to a tool the template declares, or the literal id of
a tool the project already holds. Any other id is refused at deploy.
context and auth are write-only, because a read of the server never returns
context values or the allowlist: they are kept out of the resource ledger and
re-sent on every update. Keys for a header server are minted
through the API, after the deploy.
A deploy does only what its deployer could do directly (Formations).
Besides its string properties, a { "ref_attr" } resolves the server's url,
the address its clients connect to:
outputs:
NarrationUrl:
ref_attr: Narration.url
Create a server
A server is also declarable in a template, as an
mcp_server resource.
- CLI
- SDK
- curl
naturali create-mcp-server \
--project-id proj_V1StGXR8Z5jdHi6B \
--name clareza \
--tools '[{ "tool_id": "tool_V1StGXR8Z5jdHi6B", "name": "narrate" }]' \
--context '{ "tenant": "acme" }' \
--auth '{ "type": "oauth", "mode": "allowlist", "allowlist": [{ "email": "ana@acme.com", "context": { "client_id": "c_123" } }] }'
const { data: server } = await naturali.mcpServers.createMcpServer({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'clareza',
tools: [{ tool_id: 'tool_V1StGXR8Z5jdHi6B', name: 'narrate' }],
context: { tenant: 'acme' },
auth: {
type: 'oauth',
mode: 'allowlist',
allowlist: [{ email: 'ana@acme.com', context: { client_id: 'c_123' } }],
},
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/mcp-servers \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "clareza",
"tools": [{ "tool_id": "tool_V1StGXR8Z5jdHi6B", "name": "narrate" }],
"context": { "tenant": "acme" },
"auth": {
"type": "oauth",
"mode": "allowlist",
"allowlist": [{ "email": "ana@acme.com", "context": { "client_id": "c_123" } }]
}
}'
Mint a key
For a header server. The key is returned once.
- CLI
- SDK
- curl
naturali create-mcp-server-key \
--project-id proj_V1StGXR8Z5jdHi6B \
--mcp-server-id mcps_V1StGXR8Z5jdHi6B \
--name "claude desktop" \
--context '{ "client_id": "c_123" }'
const { data: key } = await naturali.mcpServers.createMcpServerKey({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
mcp_server_id: 'mcps_V1StGXR8Z5jdHi6B',
},
body: { name: 'claude desktop', context: { client_id: 'c_123' } },
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/mcp-servers/mcps_V1StGXR8Z5jdHi6B/keys \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "claude desktop", "context": { "client_id": "c_123" } }'
Connect a client to the server's url with the key in header_name, e.g.
Authorization: Bearer nat_mcp_….
Revoke one with
DELETE /v1/projects/{project_id}/mcp-servers/{mcp_server_id}/keys/{key_id}.
Read usage
- CLI
- SDK
- curl
naturali list-mcp-server-usage \
--project-id proj_V1StGXR8Z5jdHi6B \
--mcp-server-id mcps_V1StGXR8Z5jdHi6B
const { data: usage } = await naturali.mcpServers.listMcpServerUsage({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
mcp_server_id: 'mcps_V1StGXR8Z5jdHi6B',
},
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/mcp-servers/mcps_V1StGXR8Z5jdHi6B/usage \
-H "Authorization: Bearer $NATURALI_TOKEN"
{
"data": [
{
"day": "2026-11-02",
"caller": { "type": "key", "id": "mcpk_V1StGXR8Z5jdHi6B" },
"tool_id": "tool_V1StGXR8Z5jdHi6B",
"action": null,
"count": 42,
"failures": 1
}
],
"next_cursor": null
}