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 — 74 tools across 13 domains, with provenance intact.

Setup differs between clients: file names, field names (for example url or serverUrl) and where the key goes are not the same everywhere, so follow the entry for your client. The JSON under Other MCP clients is a starting point, not a format every client accepts.

Which AI client are you connecting?

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

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

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

Connect Claude (desktop app and claude.ai)

Sign-in method: OAuth

Steps

Settings → Connectors → Add custom connector.
Paste the URL, then sign in to Numonic and approve access.

https://www.numonic.ai/mcp

How OAuth works

You don't configure anything extra. The client calls the endpoint, is told where Numonic's authorization details live (/.well-known/oauth-protected-resource/mcp), and registers itself. You then approve access on a Numonic consent page, choosing which permissions to grant.

Permissions and OAuth limits are set out in MCP authentication.

Good to know

Do not add Numonic to claude_desktop_config.json: that file only starts local servers.
Free plans allow one custom connector.

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

Check it works

Ask your client these two things, in order. Each shows the permission it needs and the tools it runs. What comes back depends on what is in your library: an empty answer from a new workspace still means the connection works. If a prompt fails, see Troubleshooting.

Read check
List the collections in my Numonic workspace.
Needs: read · Runs: ListCollections
Value check
Find my recent Midjourney images and show the generation metadata Numonic recovered.
Needs: search, read · Runs: SearchAssets, GetAssetDetails

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.

Troubleshooting

Start with the exact message your client shows. A 401 means Numonic could not identify you; a message about scope or a profile means it knows who you are and the connection lacks that permission.

Every tool fails with a generic error such as "The tool failed internally"

Why: The client could not complete the request, and Numonic never saw it. Numonic returns a message saying what was refused, so a client that shows only a generic error has usually not reached the server. A stale OAuth connection is the cause we have seen (#3441).

Fix: Disconnect the app in your client, connect it again and approve the permissions, refresh the tool list, then retry. If it still fails, check that the endpoint is exactly the one shown above.

The client says the tool call was blocked by its safety checks, or shows no Numonic message at all

Why: That message comes from the AI client, not from Numonic. Numonic answers with a message that names what it refused. We have seen this wording from a degraded ChatGPT connection even when the request reached Numonic and completed without error.

Fix: Disconnect the app in your client, connect it again and approve the permissions, then retry. If it keeps happening, send support the time (UTC) and the tool and asset involved so we can check whether the request arrived.

include_image returns the details but no picture

Why: The preview is a small JPEG or WebP thumbnail (up to 200 KB, no embedded metadata) sent as a separate image block next to the text. preview_image in the result says whether it was sent: included is false with a reason of no_thumbnail, too_large or unavailable when it was not. Some clients show the text and the image blocks in different fields, so the picture can be there but not where you looked.

Fix: Check preview_image in the result. If included is false, use GetAssetPublicUrl or the download link instead. If it is true, look for the image block in your client's tool result (ChatGPT lists the blocks under content_items).

Your client cannot find or reach the Numonic server

Why: The client is not using the endpoint, or something between it and Numonic blocks the request. A request with no credential should get a 401 whose www-authenticate header points to /.well-known/oauth-protected-resource/mcp; that is how OAuth clients learn how to sign in.

Fix: Use exactly https://www.numonic.ai/mcp, not a Supabase functions URL. To test from a terminal, run curl -i -X POST https://www.numonic.ai/mcp: a 401 with a www-authenticate header means the server is reachable and the problem is the client's setup or sign-in; no response at all points to your network or a proxy.

OAuth sign-in does not finish, or the client keeps asking you to sign in

Why: A connection only exists once you approve it on Numonic's consent page in the browser. Closing that page, signing in to a different account, or leaving without approving creates nothing, and a client can keep retrying an old connection that no longer works.

Fix: Start the connection again from the client, sign in with the account that owns the workspace, choose the workspace and permissions, and approve. Settings → Workspace → Connected Agents lists the connection once it exists. If the client still loops, disconnect it there and connect again.

"this OAuth connection has no active Numonic grant"

Why: The connection was revoked in Numonic, or it was never approved. This is an authentication failure (HTTP 401), not a missing permission.

Fix: Reconnect from your client and approve it. Settings → Workspace → Connected Agents shows which connections are active.

401 Unauthorized with an API key

Why: The key is missing, mistyped, expired or revoked, or it was sent somewhere other than a header.

Fix: Send the key in an Authorization: Bearer or X-API-Key header, exactly as your client's setup above shows. A key in the URL is rejected. Create a new key if it was revoked.

"Insufficient scope for tool …: requires 'write'"

Why: Numonic knows who you are, but the connection was not given the permission this tool needs. This is an authorization failure: the server answers with an error that names the missing permission, not with a 401.

Fix: Reconnect and approve the permission named in the message, or create an API key that includes it. See What you are granting above.

"Tool … is not part of the … profile on this connection"

Why: The connection was approved with a narrower set of capabilities than this tool belongs to.

Fix: Reconnect and choose a profile that includes it.

"Tenant ID mismatch"

Why: The client sent a tenant_id that is not the workspace your connection belongs to.

Fix: Leave tenant_id out of the call. Numonic uses the workspace your connection is bound to.

One tool fails while others work

Why: Numonic answers with a message that names what it refused, such as an argument it did not accept or a permission the connection lacks.

Fix: Read the message first. A permission message is fixed by reconnecting with that permission (see above). An argument message is fixed by correcting the call; each tool's required inputs are in the tool reference.

A tool you expect is not listed

Why: The tool list only includes tools your permissions allow, and some clients cache it.

Fix: Check the permissions you granted, then restart or reload the client so it fetches the list again.

You see the wrong workspace's assets

Why: A connection is bound to the one workspace you chose when you approved it.

Fix: Reconnect and choose the other workspace. Approving the same client for a different workspace replaces the earlier connection.

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.

Sandboxed agent with the user's own files (a chat assistant that cannot reach the network from its file environment): do not re-encode them as asset_data_base64. See Hand over files from a sandboxed assistant.

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.

Hand over files from a sandboxed assistant

Why this step exists. A chat assistant such as ChatGPT works on your files inside a locked-down sandbox. It can read them there, but the sandbox has no network access, and the Numonic connector cannot read files from it. The only way left is to paste a file's bytes into a tool call as text, which is capped at about 3 MB per file and makes the assistant spend minutes re-typing large files (they often get cancelled). So the assistant cannot upload your files itself, and you do the one step it cannot: you carry the files to Numonic in your browser. Files under about 3 MB can still be stored directly with StoreAsset and need nothing from you.

What you do.

Ask your assistant to store the files in Numonic. It calls CreateUploadLink and gives you a link, usually with the collection it will file them in.
If the assistant created the files itself, download them from the chat first (for example as a ZIP) and unzip them on your computer. The link takes the files, not the archive.
Open the link while signed in to the Numonic workspace the assistant is connected to. Anyone else, or a member of a different workspace, is refused.
Drop the files on the page, choose Upload, then I'm done. The upload goes from your browser straight to Numonic, so file size is not limited by the assistant.
Tell the assistant you have uploaded. It reads back what arrived and carries on (filing the assets, checking them).

What the assistant does. It calls CreateUploadLink (write permission) with an optional collection_path, expected_count and expected_sha1 (the SHA-1 of each file, so it can prove the right bytes arrived). After you upload it calls GetUploadLinkStatus to read back the asset_h of every file and which expected checksums matched, were missing or were unexpected.

Limits and safety. A link works for one upload session and expires (30 minutes by default, 4 hours at most). It closes when you choose I'm done or when the expected number of files has arrived. It is bound to the workspace and agent that created it, you must be signed in as a member of that workspace, and uploaded assets are attributed to that agent. The usual size, file-type and storage-quota checks apply. By default a link takes up to 50 files of up to 100 MB each.

Not supported yet. ZIP archives are stored as one file, not unpacked into their files and folders, so extract them before uploading.

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.