MCP Server

Connect Claude, Cursor, VS Code or any other MCP client to your naturali account.

Overview

naturali is a Model Context Protocol server. Every operation in the REST API is exposed as an MCP tool, derived from the same OpenAPI document the SDK and CLI are generated from — so an assistant connected to naturali can create a project, publish an agent, upload knowledge or read a trace, using exactly the surface you would call yourself.

https://api.naturali.ai/mcp

Clients authenticate with OAuth 2.1: the client registers itself, your browser opens, you approve it, and it receives its own token. Nothing needs to be provisioned in advance and no secret is copied into the client's configuration.

Two different things are called "MCP"

This page is about naturali being an MCP server that your assistant calls.

Tools covers the opposite direction — giving one of your agents access to somebody else's MCP server, by creating a tool with type: mcp. The two are unrelated; you can use either, both, or neither.

Connecting a client

Add https://api.naturali.ai/mcp as a remote (HTTP) MCP server in the client. Where that setting lives differs per client — Claude's connector settings, Cursor's mcp.json, the VS Code MCP configuration — but the handshake is the same everywhere and needs nothing from you beyond the URL:

1. The client discovers that the server requires authorization and registers itself automatically.
2. Your browser opens on the naturali console. If you are not signed in, you sign in with a code emailed to you, the same way as always (Auth).
3. A consent screen names the app and asks which projects it may reach.
4. Approving sends you back to the client, which is now connected.

If a client only supports MCP servers with a static token, see Using an API key instead below.

What you are approving

The consent screen shows the app's name and icon as the app declared them at registration — anyone can register a client and call it anything. The one detail naturali verified is the host it will send you back to, shown next to the name. If an app claiming to be Claude would return you to a domain you do not recognise, that is the signal to cancel.

A connected app acts as you. It can do what your account can do, in the projects you granted it, and everything it does is attributed to you in Traces and usage.

Choosing projects

The consent screen offers two answers, and the difference is the main security decision in the whole flow:

Choice	What the app can reach
All projects	Every project you own, including projects you create later.
Only the projects I pick	Exactly the projects you ticked. Nothing else, ever — not even another project you own.

All projects is the default because it is what most people want from an assistant, and because a connected app that cannot see a new project is a confusing thing to debug months later.

Pick the narrow option when the app is doing one job — an assistant that only works on a staging project, or a client you are trying out. A confined app that touches another project gets 403 access_denied rather than silently working; it also cannot create projects, and cannot mint a credential wider than itself.

Re-approving the same app replaces its previous answer, so you can widen or narrow an app later by connecting it again.

Managing connected apps

Settings → Connected apps in the console (app.naturali.ai/settings/apps) lists every app you have approved, what each one reaches, and when it was last used.

Disconnect takes effect immediately — not whenever the app's current token would have expired. The app's access is checked on every request, and its ability to renew is removed at the same time, so a disconnected app stops working on its next call and cannot quietly come back.

Disconnecting is the right response to a client you no longer use, a machine you no longer control, or an approval you are unsure about. Reconnecting is one consent screen away, so there is no cost to being decisive.

Using an API key instead

/mcp also accepts an API key, for clients or CI environments that cannot run a browser-based OAuth flow:

Authorization: Bearer nat_sk_…

The trade-offs are worth being explicit about. An API key is long-lived and has to be stored in the client's configuration, where OAuth gives the client its own short-lived, individually revocable token and never exposes an account secret. Prefer OAuth wherever the client supports it.

A project-scoped key confines an MCP session exactly the way a confined grant does, so this is the way to give a machine access to one project:

CLI

naturali create-api-key --name staging-assistant \
  --project-id proj_V1StGXR8Z5jdHi6B

SDK

const { data: created } = await naturali.apiKeys.createApiKey({
  body: { name: 'staging-assistant', project_id: 'proj_V1StGXR8Z5jdHi6B' },
});
// created.key is the raw nat_sk_… secret, returned exactly once.

curl

curl -X POST https://api.naturali.ai/v1/api-keys \
  -H "Authorization: Bearer $NATURALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "staging-assistant", "project_id": "proj_V1StGXR8Z5jdHi6B" }'

Troubleshooting

"Connected", but no tools and no sign-in prompt

The client believes the server is public and never started the authorization flow. Usually it has a stale entry cached from an earlier attempt: remove the server from the client, then add it again. Check the URL includes the /mcp path — pointing a client at the bare API origin is the common typo.

Every tool call fails with 401

The client's token expired and it has not refreshed, or the app was disconnected. Check Settings → Connected apps: if the app is not listed, reconnect it from the client.

A tool call fails with 403 access_denied

The app is confined to projects that do not include the one the tool named. Look the app up in Settings → Connected apps to see what it reaches, then either call a project it has or reconnect the app and widen its access.

A tool call fails with 404

The project, agent or other resource does not exist under your account. Note that 404 here means "not yours", not "not confined" — naturali never reveals whether a resource exists in someone else's account.

The client reports invalid_target

The client asked for a token for a resource this server does not serve, which almost always means a mistyped server URL.

Reference

The endpoints an MCP client discovers on its own. You should not need these unless you are debugging a client or writing one:

Endpoint	Purpose
GET /.well-known/oauth-protected-resource	Names /mcp and its authorization server (RFC 9728).
GET /.well-known/oauth-authorization-server	Authorization server metadata (RFC 8414).
POST /register	Dynamic client registration (RFC 7591).
GET /authorize	Authorization endpoint; PKCE S256 required.
POST /token	Token endpoint; authorization_code and refresh_token grants.

These sit at the API root rather than under /v1, because their paths are fixed by the OAuth and MCP specifications.

One scope is issued, mcp:access, covering the API surface an MCP client uses. Which projects a grant reaches is not part of the scope — it is the choice you make on the consent screen, recorded against the grant itself, which is why an app cannot broaden its own access by asking for more.