Connect an agent to Numonic

Numonic speaks the Model Context Protocol. Point any MCP-capable agent at one endpoint and it can search, organize, and export your creative assets — 65 tools across 13 domains, with provenance intact.

Endpoint: https://www.numonic.ai/mcp

Which path is yours?

API key — your client lets you set the server URL and a request header: desktop and IDE assistants, command-line agents, scripts, and custom agents built on an MCP SDK.
OAuth — your client only asks for a connector URL and has no field for a key or header. You approve access on a Numonic consent page.

Which credential each kind of client uses, and what each permission allows, is set out in MCP authentication.

Path 1: API key

Create a key
Sign in and open Settings → Workspace → Connected Agents. Under Create a new key, give it a name your future self will recognise (for example, the agent it belongs to) and tick only the permissions the agent needs. Read is always included; add Search for search tools, Write to add or change assets and collections, and Export to export or publish.
Copy the key when it is shown — it starts with napi_ and is displayed once. A key belongs to one workspace: everything the agent does lands there.
2
Add Numonic to your MCP client
Most clients take a JSON block like this in their MCP server settings. Replace the placeholder with your key.
```
{
  "mcpServers": {
    "numonic": {
      "url": "https://www.numonic.ai/mcp",
      "headers": {
        "Authorization": "Bearer napi_your_key_here"
      }
    }
  }
}
```
Send the key in a header only — Authorization: Bearer napi_… or X-API-Key: napi_…. A key in the URL (?api_key=) is rejected. Client-specific file locations and SDK examples are on the MCP reference.

Check the connection

Restart or reload your client and ask it to list Numonic's tools. To check from a terminal instead, list the tools:

curl -s https://www.numonic.ai/mcp \
  -H "Authorization: Bearer napi_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response should list 65 tools. Then make one read call:

curl -s https://www.numonic.ai/mcp \
  -H "Authorization: Bearer napi_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"ListCollections","arguments":{}}}'

A 401 means the key is missing, mistyped, or revoked. A permission error means the key lacks the scope that tool needs — create a key with it.

Path 2: OAuth

Rolling out: you can connect and approve access today, but tool calls over an OAuth connection are refused until per-connection permissions finish rolling out. Use an API key if your client supports one.

1
Add Numonic as a connector
In your client's connector or integration settings, add a custom MCP connector with this URL:
```
https://www.numonic.ai/mcp
```
Let the client find Numonic's sign-in
You don't configure anything here. The client calls the endpoint, is told where Numonic's authorization details live (/.well-known/oauth-protected-resource/mcp), and registers itself with Numonic's authorization server.
Approve access
You are sent to a Numonic consent page. Sign in, pick the workspace, and choose what the connection may do. Some permissions, such as administration, can only be held by an API key — see OAuth connection permissions.
Check the connection
Back in the client, ask it to list Numonic's tools and then to list your collections.

For agents and registries

/.well-known/mcp/server-card.json — the server card: endpoint, transport, accepted credentials, and a summary of the tool surface.
/api/v1/mcp-spec.json — every tool with its input schema.
/.well-known/oauth-protected-resource/mcp — OAuth protected-resource metadata.

Next: browse the full tool reference.

Connect an agent to Numonic

Endpoint: https://www.numonic.ai/mcp

Which path is yours?

API key — your client lets you set the server URL and a request header: desktop and IDE assistants, command-line agents, scripts, and custom agents built on an MCP SDK.
OAuth — your client only asks for a connector URL and has no field for a key or header. You approve access on a Numonic consent page.

Which credential each kind of client uses, and what each permission allows, is set out in MCP authentication.

Path 1: API key

Create a key
Sign in and open Settings → Workspace → Connected Agents. Under Create a new key, give it a name your future self will recognise (for example, the agent it belongs to) and tick only the permissions the agent needs. Read is always included; add Search for search tools, Write to add or change assets and collections, and Export to export or publish.
Copy the key when it is shown — it starts with napi_ and is displayed once. A key belongs to one workspace: everything the agent does lands there.
2
Add Numonic to your MCP client
Most clients take a JSON block like this in their MCP server settings. Replace the placeholder with your key.
```
{
  "mcpServers": {
    "numonic": {
      "url": "https://www.numonic.ai/mcp",
      "headers": {
        "Authorization": "Bearer napi_your_key_here"
      }
    }
  }
}
```
Send the key in a header only — Authorization: Bearer napi_… or X-API-Key: napi_…. A key in the URL (?api_key=) is rejected. Client-specific file locations and SDK examples are on the MCP reference.

Check the connection

Restart or reload your client and ask it to list Numonic's tools. To check from a terminal instead, list the tools:

curl -s https://www.numonic.ai/mcp \
  -H "Authorization: Bearer napi_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response should list 65 tools. Then make one read call:

curl -s https://www.numonic.ai/mcp \
  -H "Authorization: Bearer napi_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"ListCollections","arguments":{}}}'

A 401 means the key is missing, mistyped, or revoked. A permission error means the key lacks the scope that tool needs — create a key with it.

Path 2: OAuth

1
Add Numonic as a connector
In your client's connector or integration settings, add a custom MCP connector with this URL:
```
https://www.numonic.ai/mcp
```
Let the client find Numonic's sign-in
You don't configure anything here. The client calls the endpoint, is told where Numonic's authorization details live (/.well-known/oauth-protected-resource/mcp), and registers itself with Numonic's authorization server.
Approve access
You are sent to a Numonic consent page. Sign in, pick the workspace, and choose what the connection may do. Some permissions, such as administration, can only be held by an API key — see OAuth connection permissions.
Check the connection
Back in the client, ask it to list Numonic's tools and then to list your collections.

For agents and registries

/.well-known/mcp/server-card.json — the server card: endpoint, transport, accepted credentials, and a summary of the tool surface.
/api/v1/mcp-spec.json — every tool with its input schema.
/.well-known/oauth-protected-resource/mcp — OAuth protected-resource metadata.

Connect an agent to Numonic

Which path is yours?

Path 1: API key

Create a key

Add Numonic to your MCP client

Check the connection

Path 2: OAuth

Add Numonic as a connector

Let the client find Numonic's sign-in

Approve access

Check the connection

For agents and registries

Connect an agent to Numonic

Which path is yours?

Path 1: API key

Create a key

Add Numonic to your MCP client

Check the connection

Path 2: OAuth

Add Numonic as a connector

Let the client find Numonic's sign-in

Approve access

Check the connection

For agents and registries