Connect an agent to Numonic

What you are granting

Read this before you approve a connection or create a key. Grant only what the agent needs; you can revoke an API key or disconnect an OAuth connection at any time.

Path 1: API key

1. 1

   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 (see what you are granting). Read is always included; add Search for search tools, Write to add or change assets and collections, and Export to export or publish. Leave Admin off unless this key exists to run pipelines or register webhooks.

   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. Treat it like a password: keep it in a password manager or secrets store, not in a document, chat or repository.

2. 2

   Add Numonic to your MCP client

   A client that lets you set a server URL and request headers takes a block like this in its MCP server settings; field names vary by client. Replace the placeholder with your key. If your client can read the value from an environment variable or prompt you for it, use that instead of typing the key into the file, and never commit a file that contains it.

   {
     "mcpServers": {
       "numonic": {
         "url": "https://www.numonic.ai/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_NUMONIC_API_KEY"
         }
       }
     }
   }

   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.

3. 3

   Check the connection

   Restart or reload your client and ask it to list Numonic's tools. To check from a terminal instead, store the key in an environment variable for this shell session (the prompt hides what you paste and keeps it out of your shell history), then list the tools:

   read -rs -p "Numonic API key: " NUMONIC_API_KEY
   export NUMONIC_API_KEY

   curl -s https://www.numonic.ai/mcp \
     -H "Authorization: Bearer $NUMONIC_API_KEY" \
     -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 72 tools. Then make one read call:

   curl -s https://www.numonic.ai/mcp \
     -H "Authorization: Bearer $NUMONIC_API_KEY" \
     -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. 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

2. 2

   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.

3. 3

   Approve access

   You are sent to a Numonic consent page. Sign in, pick the workspace, and choose what the connection may do. The page offers read, search, write and export; check what each one allows first, and leave write and export unticked unless the agent needs them. Admin is never offered: it can only be held by an API key — see OAuth connection permissions.

4. 4

   Check the connection

   Back in the client, ask it to list Numonic's tools and then to list your collections.

Store images your agent generates

curl -s https://www.numonic.ai/mcp \
  -H "Authorization: Bearer $NUMONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
    "name":"StoreAsset","arguments":{
      "tenant_id":"<your tenant id>",
      "filename":"render.png","mime_type":"image/png",
      "asset_data_url":"https://v3.fal.media/files/<...>.png",
      "prompt_metadata":{"prompt_text":"<the prompt you sent>",
        "parameters_used":{"generator":"fal","model":"fal-ai/flux/dev"}}}}}'

# 1. Ask for a signed upload URL (needs a key with the write scope)
curl -s "https://www.numonic.ai/api/v1/storage/signed-url/upload?filename=render.png&contentType=image/png" \
  -H "Authorization: Bearer $NUMONIC_API_KEY" \
  -H "X-Tenant-ID: <your tenant id>"
# -> {"signedUrl":"https://...","path":"<tenant id>/uploads/..."}

# 2. Upload the bytes directly to storage (no 4.5 MB limit)
curl -s -X PUT "<signedUrl>" -H "Content-Type: image/png" \
  --data-binary @render.png

# 3. Call StoreAsset with "asset_storage_ref":{"storagePath":"<path>"}
#    and your prompt_metadata, exactly like the URL example above.

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.