Connect an MCP server
An MCP server is an outside service that offers tools Cora can call, such as a ticketing tool or a content calendar. An org admin connects one by its web address. Nothing the server offers is used straight away. On a server an org admin adds by its address for the whole organisation, every tool starts off. The org admin sets each tool’s access once, on the connection, each mission switches the connection on, and a tool set to Ask first waits for a person to approve each call. A service set up from the catalogue, or a personal connection, starts with its tools on instead (D0657, D0716).
The examples on this page follow an invented company, Kestrel Cycles, which sells e-bikes. Its marketing team is building a landing page for a spring launch, and tracks the work in an invented ticketing tool called Trackwell. Leah Thompson is the org admin who looks after the company’s software.
Before you start: turn MCP on
Section titled “Before you start: turn MCP on”MCP is off for every organisation at first. An org admin turns MCP on for the organisation with the Use MCP servers switch in Settings, Permissions, in the console. The foot of the Connections page says whether MCP is on and links there. Until then nobody can add a server. Only an org admin can change this switch (D0315).
What the MVP supports
Section titled “What the MVP supports”- Remote servers only. The server must be reachable over https and speak MCP’s Streamable HTTP transport.
- Three kinds of sign-in: none, a bearer token, or one named header with a value (for example
X-Api-Key). - Not supported in the MVP: OAuth is not supported, and neither are servers that run on your own machine (stdio), the older SSE transport, or a separate sign-in for each person. Every call to a server uses the organisation’s one credential (D0131).
Adding a server
Section titled “Adding a server”An org admin opens Connections on the left rail, presses Add any MCP server, then For everyone in your organisation, and fills in:
- A short name, such as
trackwell. It is lower case letters and digits only, with no spaces or underscores, and it must be unique in your organisation. Cora sees each tool as the short name, an underscore and the tool’s own name, for exampletrackwell_create_ticket. - The https address of the server.
- The sign-in kind and, for a bearer token or a named header, the secret.
- The approval role: the role whose holders approve this server’s write calls. It must be an admin role in your role catalogue, such as Approver. See Roles for how a role is routed to a person.
Before saving, choose Test connection. Cora connects to the address with the secret you typed, the same way it will when it is saved, and tells you “Connected. N tools found.” or why it could not connect. Nothing is saved by a test, and the secret is used for that one connection only. If the test fails, fix the address or the secret and try again; you can also save anyway and refresh later. To keep tests from being used to probe the network, each person gets ten tries in a burst and then one every ten seconds.
The secret goes straight to the secrets store and is never shown again: not on the page, not in a log, not in an audit entry and not to Cora. To change it, choose Replace secret in the connector’s menu and enter a new one. Cora’s worker reads it only while it calls the server, and keeps it in memory only.
Private and internal addresses
Section titled “Private and internal addresses”Cora checks the address when you save it and again every time it connects. Only public https addresses are allowed: private, loopback and internal addresses are refused, and so are cloud metadata addresses and a redirect to another host. So a server inside your office network, or one whose name points at a private address, cannot be connected in the MVP.
Every tool starts off
Section titled “Every tool starts off”After you save, Cora asks the server for its tools and lists them inside the connector’s card, in the Account section of the server’s own page on the Connections page (open them with Tools). Every tool starts Off. An org admin reads each one and gives it one of three settings (D0716):
- Allowed: Cora uses it without asking.
- Ask first: each call waits for a person’s approval.
- Off: Cora never uses it.
Tools are grouped by what they do. A server you add by its address gets two groups from its tools’ own hints: Read (the tools the server marks read-only) and Make changes (the rest). Each group has one setting, and Show each tool gives each tool its own; a group whose tools differ shows Mixed. Only org admins set access on an organisation connection; the owner sets it on a personal one. Turn on only the tools the team needs.
Allowed and Ask first
Section titled “Allowed and Ask first”A tool set to Ask first counts as a write: each call waits for a person’s approval. Set a tool to Allowed only when you are happy for Cora to use it without asking, such as a search or a lookup. A server can say that a tool only reads (its read-only hint), which puts it in the Read group, but the hint never decides: only the setting does. A tool the catalogue marks always-ask (such as Umbraco’s drafts) always asks: Allowed is not offered for it, or for a group that holds one (D0684).
For Kestrel Cycles, Leah sets find_ticket to Allowed and create_ticket to Ask first. She leaves delete_ticket Off.
A changed description turns a tool off
Section titled “A changed description turns a tool off”Cora keeps a fingerprint of each tool’s description. If the server changes a tool’s description, the tool is turned off until an org admin reads it and turns it on again. This stops a server from quietly changing what a tool you approved says it does.
Switching a connection on in a mission
Section titled “Switching a connection on in a mission”Setting a tool’s access does not yet let Cora use it anywhere. A connection must also be switched on in each mission, from Connections in the Tools tab of the mission’s details. A mission only switches a connection on or off: when it is on, Cora uses every tool that is not Off, with the setting the connection has (D0716). Missions do not choose tools one by one, so the same connection behaves the same way in every mission.
So the landing page mission and the newsletter mission both switch Trackwell on, and both can find and create tickets, with create_ticket asking first in each.
Write calls wait for approval
Section titled “Write calls wait for approval”When Cora calls a tool that counts as a write, it stops before the call is made (D0132):
- The holders of the connector’s approval role get an approval card in the mission dialogue and a notice, routed like any decision.
- The card shows the tool and exactly what Cora wants to send. An approver approves or rejects it. There is no editing in the MVP.
- If it is approved, Cora checks that the tool is still not Off and that its description and the call have not changed, then makes the call once. A tool set to Off while the card waits cannot be approved. If it is rejected, the call is never made.
While a call waits, Cora does no other work in that mission, and new requests wait in line. Asking never blocks: a question Cora asks the team does not wait for an approval.
An approval nobody answers expires after 48 hours and counts as a reject, so the call is not made and Cora is told not to try again without asking. Cora then posts in the mission that she did not run the tool because it was not approved in time. Approvals are checked for expiry every 5 minutes, so one can expire up to 5 minutes after its due time. A mission’s skill pack can set a longer time, up to a week (D0314). When a mission has more than one pack, the longest time any of them sets applies.
When a connector is failing
Section titled “When a connector is failing”A connector is marked failing when Cora cannot reach the server or the server refuses it: the server is down, the credential is wrong or has expired, or the address now points somewhere that is refused. The connectors page shows it as failing with the reason. While it is failing, Cora carries on with its other tools and skips that server. Fix the cause (for example, choose Replace secret and enter a new token), then choose Refresh on the connector’s card.
What the operator can do
Section titled “What the operator can do”The Cora AI operator keeps two safety controls that no organisation can change (D0131):
- A deny list of addresses no organisation may connect.
- A kill switch for each connector. A blocked connector shows as blocked by the operator, and its tools leave Cora’s tool list from the next run. When the operator lifts the block, its tools come back as they were.
Proving it safely
Section titled “Proving it safely”Before you rely on a server, try it in a test mission with tools that cannot do harm. Cora AI keeps its own test tools for this, described in the test tools reference. They are on only in organisations where the operator has turned them on.
Coming next
Section titled “Coming next”- Removing a connector from the page. For now, turn its tools off.
- Connecting with OAuth, servers on your own machine and a separate sign-in for each person come later.
- An organisation setting that limits connections to an operator-approved list arrives in Phase 5 (D0131).