MCP servers

An MCP server exposes tools over the Model Context Protocol. Cengrid discovers the server’s tools and schemas and makes them available to the agent in the scopes where the server is added. Credentials stay in core’s encrypted keychain.

Declare servers in a plugin

Put an mcpServers object in mcp.json at the plugin root, or point the manifest’s mcpServers field at a file or an inline object.

mcp.json

{
  "mcpServers": {
    "docs-search": {
      "name": "Docs search",
      "description": "Search the internal documentation",
      "url": "https://mcp.example.com/docs",
      "readOnly": true
    }
  }
}

Do not put real tokens in the file

Repository credentials are discarded on import. If the file includes an Authorization: Bearer ... header, the importer records only that the server wants bearer authentication. You enter the token when you add the server to a scope.

Field	Meaning
Key (docs-search)	The server id. Lowercase letters, digits and hyphens, starting with a letter, 2 to 40 characters.
url	Required. A fixed http or https endpoint with no credentials, query string, fragment or ${...} placeholder.
name, description	Optional display text. name defaults to the key.
headers	Only Authorization with a Bearer value is accepted. It marks the server as bearer-authenticated; any other header makes the server unavailable.
readOnly	Defaults to true. Set false to declare the server as able to write.

Legacy .mcp.json is accepted. Servers that need stdio (command), SSE or custom headers are listed as unavailable with the reason, never altered to make them run. A URL containing a ${...} placeholder is unavailable too, or rejects the plugin if it cannot be parsed as a URL.

Add a server to a scope

1. Connect the plugin, then open MCP Servers → Available for the organisation or a team.
2. Choose the server, enter the bearer token if it needs one, and add it.
3. Use Test connection. Cengrid builds a fresh client, runs the full handshake and discovers tools. The result is stored as Working, Reachable or Failing.

Saving a server whose test fails is refused. If a plugin’s endpoint later changes on re-sync, the saved token is discarded and the server is disabled until you add it again with a new token. Credentials are only reused for an unchanged endpoint.

Create one without a plugin

On MCP Servers choose Create MCP server. A custom server supports:

• No authentication, a bearer token, an API key in a named header, a Google service account, or the client-credentials flow. Client credentials exchange a client id and secret at a token endpoint, which defaults to the server’s adjacent /token. An explicit endpoint may be on another host and is subject to egress policy.
• Additional headers: up to 20, sent on every request. Names are lower-cased. authorization, cookie, host, framing, content-type and MCP session headers cannot be set. Values are visible to administrators, so secrets belong in the authentication fields.
• Read-only, which keeps the administrator-declared tool classification. Cengrid does not inspect arbitrary upstream tools to prove they cannot write.

Cengrid does not do general OAuth discovery for MCP servers. Use the connection test to see exactly what a token endpoint answers before relying on a service account.

Scope and overrides

An MCP server added at the organisation is inherited by teams. A team can configure its own server with the same id, which takes precedence for that team and is marked Overrides organisation. A team server keeps its own readOnly setting. Personal MCP servers live in the person’s Keychain and are used only in their private scope.

Enforcement is the same as for other capabilities: the organisation’s and scope’s egress settings and the turn’s security posture apply to discovery and calls. See secrets and egress.