External integrations & MCP tokens

Where this lives: AI Agents → External integrations in your dashboard sidebar.

This page is where you let outside tools — Claude Desktop, ChatGPT desktop, n8n, Zapier, Make.com, custom scripts — talk to your Coffield.io workspace.

Think of an MCP token as a hotel keycard you cut for a specific contractor:

• It only works on the doors you check off when you cut the card (each toolset = one set of doors).
• It expires when you say it does.
• You can punch a single card without affecting any of the others.
• The card is shown to you once, at issue time. Lose it, and you cut a new one.

You do not need to know what JSON-RPC is to use this page. Each toolset card already lists the things the outside tool can do in plain English.

#When should I use this page?

#Shopify owners

If you are on Shopify, use this sequence first:

1. Dashboard -> Integrations -> External integrations.
2. Connect Shopify (OAuth).
3. Install storefront widget.

This is the standard owner workflow and does not require manual theme file edits in normal cases.

MCP tokens are the best fit when the outside tool is agentic — something that decides on its own which action to take next (Claude Desktop, an n8n agent node, a custom assistant). For one-off "send Slack on lead created" automations, outbound webhooks are simpler.

#The six toolsets

Each card on the page is one toolset. You can grant any combination to a single token.

Plain-language note: "Growth" means "Growth plan or above." Pro and Custom inherit everything Growth gets.

Locked toolsets show an amber banner with a View plans → link instead of being hidden — so you always know what upgrading would unlock.

#Cutting a token (step by step)

1. Go to AI Agents → External integrations.
2. Scroll to the Create a token form.
3. Type a name you'll recognize later (e.g. "Claude Desktop — my laptop" or "n8n — production"). This name is for you only; outside tools never see it.
4. (Optional) Set an expiry. Leave it blank for "never expires" — but for tokens you give to a contractor, set a date.
5. Check the toolsets this token should be allowed to use. Less is better — start with one or two and add a new token later if you need another.
6. Press Create token.
7. Copy the token immediately. It is shown to you exactly once. Coffield.io stores only a hash, not the token itself, so we cannot retrieve it later.
8. Paste it into the outside tool's MCP configuration. Each tool has its own UI:
   • Claude Desktop: Settings → Developer → Edit Config, add an entry under mcpServers with the toolset's endpoint URL (visible on each toolset card) and Authorization: Bearer <your token> header.
   • n8n: add an MCP Client node, paste the endpoint URL and bearer token.
   • Zapier / Make.com: use the generic HTTP module, POST JSON-RPC envelopes to the endpoint URL with Authorization: Bearer ... header.

If you forget to copy the token, revoke it and create a new one — it cannot be re-shown.

#Reviewing what a token can see

The Active tokens table on the page shows you:

Revoking is instant — the next request that token makes returns 401.

Compromised token? Revoke first, ask questions second. The token is dead the moment you click Revoke.

#The Training toolset — operator review workflow

This is the only toolset that writes into your knowledge base, so it has the most important safety pattern in the whole system. Read this section before you grant the Training toolset to any external tool.

#What outside tools can do

• add_training_item — push a new knowledge item (title + content + optional summary/category).
• update_training_item — edit one of the drafts they previously pushed.
• archive_training_item — pull an item out of rotation.
• list_training_drafts — see what is sitting in your review queue.

#What outside tools cannot do

• Activate knowledge. Every item pushed via the Training MCP lands in your workspace as a draft with a "system suggested" flag, and your assistant never sees it until you promote it.
• Edit live knowledge. Once you promote an item, the Training MCP refuses to touch it. External tools cannot silently rewrite the answer your assistant gives.

This means even a stolen Training token cannot poison what your assistant says. The worst it can do is fill your review queue with spam — and the Revoke button takes care of that.

#How to review what's been pushed

1. Go to AI Agents → Agents and open the relevant agent.
2. Scroll down to the What the agent knows section.
3. The filter row above the table has two filters:
   • Visibility — set it to Draft to see only items pending review.
   • Source — set it to Pushed by external tool to see only items the Training MCP added (vs. items you typed by hand).
4. The Source column shows a blue External tool badge on items pushed by the Training MCP — hover over it for a one-line warning ("Pushed by an external tool via the Training integration. Review carefully before promoting to Live.").
5. Click any draft row to open the editor.
6. Read it. Read it carefully. This is the moment of trust.
7. If you're happy, change Make available to the agent from Draft to Live and save. Your assistant will start using it within a minute.
8. If you don't want it, either:
   • Change Make available to the agent to Hidden — leaves an audit trail.
   • Delete from the row actions — removes it entirely.

#Healthy review habits

• Check the draft queue at least weekly.
• If you see a flood of drafts you didn't expect, revoke the Training token first.
• The Source = Pushed by external tool filter is the fastest way to bulk-find Training-MCP items if you want to review just those.

#What happens if a token is misused

Every MCP request is checked at four layers:

1. Token validity — revoked or expired? 401, denied.
2. Toolset scope — token tried a toolset you didn't grant? 403, denied.
3. Plan tier — downgraded since you cut the token? 403 with a friendly upgrade prompt.
4. Abuse guard — if a token is used more than 250 times in a single minute, it's auto-throttled to 429 (per-token, not per-IP — so rotating IPs doesn't help). If an IP fails authentication more than 10 times in an hour, the whole IP is locked out for the rest of the hour.

You don't have to configure any of this — it just runs.

#The endpoint URLs (for your developer)

Each toolset card shows its endpoint, but for reference:

All endpoints speak JSON-RPC 2.0 and support initialize, tools/list, tools/call, and ping. Any MCP-compliant client (Claude Desktop, Cursor, n8n MCP node, etc.) will detect the tools automatically.

If your developer wants the raw schema, point them at the tools/list response after authenticating — every tool's input schema is published there in JSON Schema draft-07 format.

#Troubleshooting

If you're still stuck, email support@coffield.io with the token name (never the token itself) and the toolset that's misbehaving.