Skip to main content

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​

FieldTypeDescription
idstringPublic MCP server ID (mcps_ prefix).
project_idstringThe owning project.
urlstringWhere 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.
namestringserverInfo.name.
titlestring, nullableserverInfo.title.
instructionsstring, nullableinstructions in the initialize result.
logostring, nullableserverInfo.icons; an https URL.
website_urlstring, nullableserverInfo.websiteUrl.
toolsobject[]tool_id, action, and the name and description clients see; at most 100.
tool_modelist | compactlist lists every tool; compact serves search, describe and call over them.
context_keysstring[]The keys of the stored context; values are never returned.
authobjectWho may connect. See Auth.
daily_call_limitinteger, nullableCalls per UTC day. Required when auth is none.
created_atstring (date-time)
updated_atstring (date-time)
unavailable_toolsobject[]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.

FieldTypeDescription
idstringPublic key ID (mcpk_ prefix).
project_idstringThe owning project.
mcp_server_idstringThe server the key opens.
namestring, nullableLabel.
key_prefixstringThe start of the key, to tell keys apart.
context_keysstring[]The keys of the stored context; values are never returned.
created_atstring (date-time)
keystringThe 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:

LayerSet on
Servercontext on the server
Callercontext on an allowlist entry or a header key; a tenant issuer's context_claims
Platformnaturali_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.

authWho 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), optional scopes and context_claims. naturali checks every token: the signature by a key of jwks_uri (RS256, ES256 or EdDSA), iss equal to issuer, exp, nbf, aud naming the server's url, and every one of scopes in its scope (or scp) claim. The token is never forwarded to a tool. context_claims maps a tool_context key 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 resource parameter (RFC 8707), and to issue tokens whose aud is the server's url.

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:

ItemAdds to the bound
An actionEach 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-memoriesmemories:ListMemories also on the preset memory_store_id's store.
search-knowledgeembeddings: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>}} presetThe pin resolved from the caller's context, so an OAuth caller with x_case in its context reaches that case and no other.
call-tooltools: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_connectionoauth-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​

LimitCountsOver it
daily_call_limit, per UTC dayTool calls by every caller: tools/call, or call on a compact server429 QUOTA_EXCEEDED with meta.window: day, Retry-After until midnight UTC
600 requests per minute, on every serverEvery request a caller is let in for, tools/list included429 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.

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" } }] }'

Mint a key​

For a header server. The key is returned once.

naturali create-mcp-server-key \
--project-id proj_V1StGXR8Z5jdHi6B \
--mcp-server-id mcps_V1StGXR8Z5jdHi6B \
--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​

naturali list-mcp-server-usage \
--project-id proj_V1StGXR8Z5jdHi6B \
--mcp-server-id mcps_V1StGXR8Z5jdHi6B
{
"data": [
{
"day": "2026-11-02",
"caller": { "type": "key", "id": "mcpk_V1StGXR8Z5jdHi6B" },
"tool_id": "tool_V1StGXR8Z5jdHi6B",
"action": null,
"count": 42,
"failures": 1
}
],
"next_cursor": null
}