Connect an MCP client to your Node

Your Node already knows everything you would open the Console to find out: which events arrived, which sales were recorded, what failed silently, how much each ad spent. The MCP endpoint hands that to an AI agent of yours — Claude Desktop, an IDE agent, a tool you wrote yourself — so you can ask in plain language instead of navigating screens.

The agent reads from your Node, with a key of yours, straight from your server. Nothing is brokered by Supreme.

Time required: 10 minutes.

What the Node's MCP endpoint is

MCP (Model Context Protocol) is the protocol an AI client uses to discover and call tools. The Node exposes its own at a single address:

POST https://YOUR-NODE/mcp/dispatch.php

The characteristics that matter when configuring a client:

If your Node is installed so that the domain root already points at the public folder, https://YOUR-NODE/public/mcp/dispatch.php answers as well. Both forms reach the same place; use whichever returns 200 in the Step 2 test.

The key: MCP_KEY

Why it is not the MASTER_KEY

The MASTER_KEY is the Node's administrative key. Whoever holds it gets into the Console, changes configuration, creates and deletes Properties, edits integration credentials. Handing the MASTER_KEY to an AI agent would be handing over the whole Node.

MCP_KEY exists precisely so that is never necessary. It opens only the MCP endpoint, and the MCP endpoint only reads. They are different keys, stored separately, and one does not substitute for the other:

• pasting the MASTER_KEY into the X-MCP-Key header returns 401;
• the MCP_KEY will not get you into the Console.

The endpoint accepts a second header, X-Agent-Key, which is the lane the System itself uses for assisted features. To connect your own agent, use X-MCP-Key.

Where it lives

MCP_KEY sits in the Node's .env file on your server, and also in the Node's internal settings — that second copy is what guarantees an update never leaves the endpoint without a key.

From version 4.0.0 onward it is minted during installation. A Node installed before that gets one on its first update to 4.0.0.

An update never rotates the MCP_KEY. When one already exists, the Node leaves it alone. If your agent stopped working after an update, the cause is somewhere else.

The MCP_KEY does not appear on any Console screen. It is read from the Node's .env file, and that is deliberate: a key no interface displays is a key that cannot leak in a screenshot.

Step 1 — Get the MCP_KEY

Reach your server over SSH or through your host's file manager and open the .env at the root of the Node installation. Look for the line:

MCP_KEY=...

The value is a long hexadecimal string. Copy the whole thing, with no whitespace.

If the line does not exist, the Node predates 4.0.0 and has not been updated yet. Update to 4.0.0 or newer and it appears.

Treat the MCP_KEY like a password: it does not go into a public repository, a shared prompt, or a support ticket.

Step 2 — Test the endpoint before configuring the client

This separates "the Node is not answering" from "my client is misconfigured". From any terminal:

curl -s -X POST "https://YOUR-NODE/mcp/dispatch.php" \
  -H "X-MCP-Key: YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

What the response tells you:

A shorter test, just to prove authentication:

curl -s -X POST "https://YOUR-NODE/mcp/dispatch.php" \
  -H "X-MCP-Key: YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Step 3 — Configure the client

Every MCP client declares remote servers in its own way, and field names vary. What does not vary is what you have to supply: the URL, the header, and the key.

The most common shape looks like this:

{
  "mcpServers": {
    "supreme-node": {
      "url": "https://YOUR-NODE/mcp/dispatch.php",
      "headers": {
        "X-MCP-Key": "YOUR_MCP_KEY"
      }
    }
  }
}

Replace YOUR-NODE with your Node's domain and YOUR_MCP_KEY with the value from Step 1. Check your client's documentation for where that file lives and how it names the URL and headers.

After restarting the client, ask it to list the available tools. 11 should appear.

What the agent can ask

There are 11 tools, in five families.

Diagnostics and logs — 4 tools

node_list_diagnostics · node_get_diagnostic · node_ack_diagnostics · node_search_logs

The Node detects silent failures as it processes: a sale with no identifier, an event refused in validation, a forwarding attempt that failed, a rejected webhook. Every finding carries a code, level, status, message and operational context. System logs can be searched by level, channel, text or event id.

"Is anything failing silently on my Node in the last few days? Show me the log for the most serious finding."

Events and payloads — 2 tools

node_get_events · node_get_event_payload

The list of recent events, with filters, and the stored payload of one event or one purchase at a time.

"Did any purchase arrive in the last hour? Open the payload of the latest one and tell me whether it carried utm_content."

Purchases — 1 tool

node_get_purchase_summary

Total revenue, count and breakdown by platform over a period. Aggregated, never row by row.

"How much revenue did the Node record in the last 30 days, by platform?"

Integrations — 1 tool

node_list_integrations

Which integration modules are installed on this Node and whether they are active.

"Which integrations are installed and active here?"

Ads — 3 tools

ads_list_connections · ads_get_summary · ads_get_insights

The same reads as the Console's Insights section: the connected accounts and their sync state; the spend, CPA and ROAS summary for a period with the daily series; and performance aggregated by ad, ad set or campaign — optionally cross-checked against the revenue the Node measured.

"How did the ads do over the last 7 days? List the 10 highest-spending ads with the attributed ROAS of each."

The per-ad join depends on the utm_content macro on your creatives, exactly as it does in the Console — see Connect Meta Ads to your Node.

What the agent cannot do

The endpoint reads. It does not create, configure or forward anything.

• No configuration changes. There is no tool that creates a Property, installs a module, edits a credential, triggers a forward, or changes a Node setting.
• No credential leaves. The integrations list omits module configuration. The ads connection list never returns the access token.
• Payloads pass through a redactor. When an event or purchase payload is opened, personal data is masked inside the Node, before the response leaves. The agent can quote a mask; it never receives the real value.
• One record per call. Payloads are read one event or one purchase at a time — there is no date range and no bulk export down this path.

One exception, worth knowing: node_ack_diagnostics writes. It marks diagnostic findings as read or resolved — the same thing you would do by clicking in the Console. It is the only tool that changes state, it touches neither configuration nor event data, and "read" is a fact about you: instruct your agent to mark findings only with your explicit confirmation.

Troubleshooting a 401

A 401 with AUTH_INVALID_MCP_KEY means one thing: the key sent does not match the one the Node holds. It is not a firewall, not CORS, not the model.

Check in this order:

1. Is the header X-MCP-Key? Not Authorization, not X-Master-Key.
2. Is the value complete? Copying from a terminal tends to clip the end or paste a line break in the middle. Compare the first and last characters against the .env.
3. Is it really the MCP_KEY? MASTER_KEY and INGEST_TOKEN live in the same file and are just as long. The MCP endpoint accepts neither.
4. Does an MCP_KEY= line exist in the .env? If not, the Node predates 4.0.0 or has not been updated. With no key configured the endpoint refuses everyone, always — including a correct key from a different Node.
5. Is it the right Node? Each Node mints its own MCP_KEY. A staging key will not open production.

An update is not a likely cause: the Node preserves an existing MCP_KEY when it updates.

If the Step 2 curl test answers and the client does not, the problem is in the client configuration — nearly always the header, which some clients expect in a differently named field.

Good practice

• One key per Node. Do not reuse the same MCP_KEY across Nodes; each one mints its own.
• Always prefer HTTPS. The key travels in a header; without TLS it travels in the clear.
• Review before approving a write. Configure your client to ask for confirmation before calling node_ack_diagnostics.
• Treat the answer as your business data. The agent reads from your server, but what you do with the answer afterwards — pasting it into a chat, into a shared document — is on you.

To connect the ad account that feeds the three ads tools, see Connect Meta Ads to your Node.