Connect Numonic to your AI client

Numonic speaks the Model Context Protocol. Pick your client and it can search, organize, and export your creative assets — 72 tools across 13 domains, with provenance intact.

Which AI client are you connecting?

Pick yours and we show the recommended way to connect it.

Claude ChatGPT Gemini Grok Le Chat Perplexity Copilot Studio Claude Code Codex Gemini CLI VS Code Cursor Devin DesktopSelected TypeScript SDK Python SDK Other clients

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

Connect Devin Desktop (formerly Windsurf)

Sign-in method: API key

First, create a key

Open Settings → Workspace → Connected Agents, create a key and tick only the permissions the agent needs. The key starts with napi_ and is shown once.

Steps

Add to ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows). Replace YOUR_NUMONIC_API_KEY with your key, or use your client's environment-variable or secure-input option if it has one, and do not commit a file that contains the key.

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

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. Send the key in a header only (Authorization: Bearer napi_… or X-API-Key: napi_…); a key in the URL is rejected.

Devin Desktop documentation · Checked against the client's docs on 2026-09-28.

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.

What each Numonic permission allows, and where it can be granted
Permission	Allows	OAuth connection	API key
read	View assets, collections and their details.	Yes	Always included
search	Search your library.	Yes	Optional
write	Add and update assets, tags and collections, and remove tags and annotations.	Yes	Optional
export	Export and publish assets and collections.	Yes	Optional
admin	Run pipelines and register webhooks.	Never granted	Optional

write: Changes your library. An agent with write can edit or remove what is already there.
export: Sends content out of Numonic. Published collections and exports can be opened by people outside your workspace.
admin: Broadest permission. Use a dedicated key for it, not the key your everyday agent uses.

Store images your agent generates

Generator returns a URL (fal, Replicate, Comfy Cloud, Midjourney): pass it to StoreAsset as asset_data_url with the prompt you used. Numonic fetches the file server-side. Store it promptly: Replicate URLs expire after an hour.

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

Generator returns bytes (image APIs that send the file back instead of a link), or the file is larger than about 3 MB: small files can go inline as asset_data_base64, but MCP requests are capped at 4.5 MB. An agent that can run shell commands should upload the file itself, then reference it.

# 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.

Record which generator made the image as plain strings in prompt_metadata.parameters_used (generator, model). Only send what you actually called. Assets stored this way are counted as agent-generated.

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.