> ## Documentation Index
> Fetch the complete documentation index at: https://user-docs.olyrosstudios.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP servers

> Bring your own tools to your agents by registering the MCP servers your company runs.

A company registers its own remote MCP (Model Context Protocol) servers so agents can
use the company's internal tools. Olyros discovers the server's tools, lets an admin
choose which are exposed and to which agents, mounts the server into the agent runtimes,
and handles authentication, including per-person OAuth where the server needs to know
who is asking. Admin pages are the sidebar entry **MCP Servers** in the **Agents** group
(`/settings/mcp-servers`, `/settings/mcp-servers/new`, `/settings/mcp-servers/:id/edit`)
and each agent's **MCP servers** tab (`/agents/:agentId/mcp-servers`); people manage their
own sign-ins under the sidebar entry **Connected Accounts** in the **Settings** group
(`/settings/mcp-connections`).

## What it does

* **Register a server** (`createMcpServer`, `updateMcpServer`, `deleteMcpServer`):
  `slug` (`^[a-z0-9_]{1,24}$`, no leading, trailing or double underscore, prefix
  `olyros_` reserved), display name, description, `url` (http(s), https when
  credentials are sent, no `user@host`, egress-checked against private and metadata
  ranges), `transport` `streamable_http` (default) or `sse`, `auth_mode` `none`
  (default), `static_secret` (encrypted headers sent on every call) or
  `oauth_per_user`; `oauth_company` exists in the enum but is rejected as not supported
  yet. `is_active` switches a server off without deleting it.
* **Discover and curate tools.** `discoverMcpServerTools` fetches the tool list and
  stores name, description, input schema and annotations (`McpServerTool`); a company
  may run at most 20 discoveries per hour.
  `allowed_tools` (or `allow_all_tools`) decides what agents see;
  `setMcpToolAccessOverride` adjusts one tool; `setMcpServerSkillCodeEnabled`
  controls whether skill code may call the server.
* **Mount into runtimes.** `runtimes` is a list of `server_agent` (default; the
  in-server chat agent for web and Slack) and `sandbox` (the long-lived per-user
  sandbox; requires an explicit `allowed_tools` list). `cloud_task` is refused: "cloud
  tasks cannot use MCP servers".
* **Bind to agents** (`bindMcpServerToAgent`, `unbindMcpServerFromAgent`,
  `agentMcpServers`); binding a sandbox agent is checked against the server's
  runtimes.
* **Per-user OAuth.** For `oauth_per_user` servers Olyros registers itself as an OAuth
  client with the server when needed, a person starts the flow (`startMcpOAuth`),
  consents at `POST /api/mcp/oauth/consent` and returns through
  `GET /api/mcp/oauth/callback` (PKCE state: `pending`, `used`, `expired`, `denied`).
  The credential is stored per **principal**, the identity of a person across channels
  (`olyros_user` or `slack`), with status `active`, `revoked` or `refresh_failed`,
  refresh scheduling and the upstream subject and email when the server reports
  identity. An optional `identity_issuer` (https OpenID issuer) lets Olyros check the
  signed-in identity. People list and revoke their own connections
  (`myMcpConnections`, `revokeMcpCredential`); admins see everyone's
  (`mcpServerConnections`, `revokeMcpConnection`).
* **Use is recorded.** Each tool call outcome is logged as `ok`, `auth_required`,
  `error` or `denied`, which is how an agent knows to ask a person to connect. When the
  conversation came in through a [router](https://user-docs.olyrosstudios.com/routers.md), the sign-in prompt and its
  follow-ups leave through the router's Slack app.

## Who can use it

* Register, update, delete, discover tools, tool overrides, skill-code switch, bind to
  agents, see all connections, revoke another person's credential: **company admin**
  (ability `mcp.manage`, listed under **Settings -> Roles**, `/settings/roles`).
* List servers and tools, see an agent's servers, start your own OAuth connection
  (`startMcpOAuth`, membership only, at most 10 starts per person per hour) and revoke
  it: **any company member**.
* No plan or tier gate.

## How to configure it

1. Agents -> MCP Servers (`/settings/mcp-servers`) -> New (`/settings/mcp-servers/new`,
   `createMcpServer`): slug, URL, transport, auth mode;
   for `static_secret` add the headers; for `oauth_per_user` add scopes and, if the
   server publishes identity, the issuer.
2. **Discover tools**, then pick the allowed tools (or allow all) and the runtimes.
3. On each agent's MCP servers tab (`/agents/:agentId/mcp-servers`), bind the server
   (`bindMcpServerToAgent`).
4. For per-user servers, each person opens Settings -> Connected Accounts
   (`/settings/mcp-connections`) and connects (`startMcpOAuth`); an agent that gets
   `auth_required` will prompt them.
5. Review connections and revoke as people leave (`mcpServerConnections`).

## Limits and defaults

| Setting | Default | Where enforced |
| - | - | - |
| `transport` / `auth_mode` | `streamable_http` / `none` | model defaults |
| `runtimes` | `["server_agent"]` | registry validation; `sandbox` needs `allowed_tools` |
| Slug | 1–24 chars `[a-z0-9_]`, no `__`, no `olyros_` prefix | registry validation |
| Display name / description / URL length | 120 / 2000 / 2048 characters | registry validation |
| Allowed tools | at most 500 names | registry validation |
| URL | http(s); https when credentials are sent; no credentials in URL; egress check | registry validation |
| Identity issuer | https, no credentials, no query or fragment | registry validation |
| Header values | no newlines | registry validation |
| Tool discovery | 20 per company per hour | per-company rate limit |
| OAuth starts | 10 per person per hour | per-person rate limit |
| OAuth state lifetime | 10 minutes | OAuth state |

## What it emits

* Discovered tool catalog per server with annotations history.
* Credential rows per person and server with refresh state; OAuth state rows.
* Per-call use records (`McpCredentialUse`) with outcomes.
* Agent bindings visible on the agent page.

## Known gaps

* Not available to one-shot cloud tasks (`cloud_task` runtime refused), so scheduled or
  workflow-dispatched tasks cannot call MCP servers.
* No company-wide OAuth (`oauth_company`), only per person or static secret.
* Remote servers only: no stdio servers and no servers hosted by Olyros for a company.
* No per-tool approval gate; a bound tool is callable once allowed.

## Customer-safe summary

Bring your own tools to your agents by registering the MCP servers your company runs.
Olyros reads the server's tool list so you can choose exactly which tools each agent may
use. Servers can be open, protected by a shared secret, or require each person to sign in
with their own account, in which case agents act with that person's permissions and
people can see and revoke their own connections at any time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.