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 StudioSelected Claude Code Codex Gemini CLI VS Code Cursor Devin Desktop TypeScript SDK Python SDK Other clients

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

Connect Microsoft Copilot Studio

Sign-in method

OAuth(recommended)API key

Steps

Your agent's Tools → Add a tool → New tool → Model Context Protocol.
Enter the URL, then choose OAuth 2.0 → Dynamic discovery.

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.

Copilot Studio 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.