> ## 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. # Agent access (MCP connections) > Agent access lets you connect a coding agent running on your own computer to your Olyros company. Agent access lets a member hand a coding agent on their own machine (Claude Code, Codex CLI or any MCP client) a connection to Olyros that acts as them, in one company, within scopes they choose. The agent reaches Olyros through the hosted MCP endpoint `/api/mcp` and sees the same objects the member sees in the client app, never more than the member's role allows. Connections are managed under **Settings -> Agent access** (`/settings/agent-access`). The page written for the agent itself, with the object model, the scopes in detail and every tool, is [olyros-for-agents.md](https://user-docs.olyrosstudios.com/olyros-for-agents.md); this page covers what a company can do with connections and how they are governed. ## What it does * **A connection is a scoped, expiring, revocable token.** It belongs to one member in one company and carries a name (what the member calls it, "laptop claude code"), a set of scopes, an expiry date and, once used, a last-used time. The token is shown once, when the connection is created; Olyros keeps only a one-way hash and the first twelve characters for display (`olyros_ac_3f…`). A revoked connection stays in the list for the record and can be shown with the **Include revoked** switch. * **The agent acts as the member.** Every call runs as the member who created the connection, in that company, with the member's role: an agent connected by a viewer cannot create what the viewer could not create, and an admin's connection is still bounded by its scopes. The company is fixed by the connection; the agent cannot switch companies. Removing a member from the company revokes every connection they hold in it in the same step. * **Scopes bound what the agent may touch.** A scope is `:` for one of six domains (`agents`, `environments`, `executors`, `oho`, `sandboxes`, `skills`) with `read` or `write` access; `write` implies `read`. The form offers one access level per domain (no access, read, read and write). A connection holds any non-empty subset of the twelve scopes. Everything outside the six domains (users and roles, billing, integrations and credentials, Slack, workflows, schedules, memories, usage, platform administration) is unreachable through a connection, whatever its scopes. MCP servers can be read (the catalog), not managed: the `skills` domain covers the skill library and the registered MCP servers with their discovered tool catalogs, never their credentials or who is connected to them. A connection cannot create or revoke connections. * **Some operations are excluded for every connection.** Revealing a stored environment or sandbox overlay secret, rotating an OHO's device credentials, looking up a pending OHO registration by its token, connecting, verifying, capping or revoking a bring-your-own Google Cloud backend, changing an agent's Access table and changing an agent's Slack reply options are refused for every connection, whatever its scopes and the member's role. * **Nine tools.** Four generic tools (`olyros_whoami`, `olyros_schema`, `olyros_graphql`, `olyros_docs`) cover the whole surface: the connection's identity, the GraphQL schema of one domain cut to the connection's scopes, one GraphQL operation per call, and the product documentation (also offered as MCP resources). Five curated tools answer the common asks without the agent writing GraphQL: `create_runtime_environment`, `clone_runtime_environment`, `list_agents`, `upload_skill_bundle` and `download_skill_bundle`. Destructive mutations (names starting with `delete`, `revoke`, `archive` or `rebuild`) and `updateSkillTrustProfile` need an explicit `confirm` flag, so the agent asks the person first. * **Every refusal names its reason.** A call outside the scopes answers with the missing scope (`SCOPE_REQUIRED`), one outside the domains with `UNKNOWN_FIELD`, an excluded operation with `FIELD_EXCLUDED`, a destructive one without confirmation with `CONFIRM_REQUIRED`; the full list is on the agents page. A scope check happens before anything runs, so a refused call changes nothing. * **What an agent did is visible.** Each connection shows when it was last used, and its row expands into an activity list (`agentConnectionActivity`): the mutations the agent ran, newest first, with action, resource, operation name, client and tool. The page loads the last 50; the query returns up to 200. Reads leave no row. * **Agent access can be switched off for a deployment.** When it is off, the endpoint answers as if it did not exist and no connection works; the Settings page stays as the place where connections are managed. ## Who can use it * **Any company member** can create connections for themselves (`createAgentConnection`), list their own (`agentConnections`), see the scope list (`agentConnectionScopes`), read the activity of their own connections (`agentConnectionActivity`), issue a new token for their own connection (`rotateAgentConnectionToken`) and revoke their own connections (`revokeAgentConnection`). There is no separate ability to hold a connection: a connection can do what its member can do, narrowed by its scopes. * **A member with `user.manage` (company admin)** can switch the list to every member's connections (`agentConnections` with `allMembers: true`, the default view for admins), read the activity of any connection, and issue a new token for or revoke any connection of the company. The page shows the **All members** switch only to such a member. * **The agent** needs nothing beyond the token. Its calls are checked against the connection (not revoked, not expired, member still active in the company) and then run with the member's role; the Google SSO policy of the company applies to the member behind the connection as it does to their browser session. * No plan or tier switches agent access on or off. The billing session gate and the structural gates that apply to the member in the client app apply to the agent's calls unchanged (see [billing-and-usage.md](https://user-docs.olyrosstudios.com/billing-and-usage.md)). ## How to configure it 1. Open **Settings -> Agent access** (`/settings/agent-access`) and choose **New connection**. 2. Give the connection a name (1 to 80 characters), pick an access level per domain (at least one domain must have read or write access) and an expiry: 30, 90 or 180 days, 90 by default. The dialog submits `createAgentConnection(name, scopes, expiresInDays)`. The server rejects an empty or overlong name, an unknown scope, an empty scope list and an expiry outside 1 to 180 days. 3. Copy the token from the confirmation step; it is not shown again. The dialog also offers the two client configurations, with the token filled in: ``` claude mcp add --transport http olyros /api/mcp --header "Authorization: Bearer " ``` ```json theme={null} { "mcpServers": { "olyros": { "type": "http", "url": "/api/mcp", "headers": { "Authorization": "Bearer " } } } } ``` `` is the API base of the Olyros deployment the company uses; the connection's `mcpUrl` field carries the full endpoint and the dialog fills it in. 4. In the agent, call `olyros_whoami` first: it returns the company, scopes, expiry and the member's role and abilities, and tells the agent what it may do before it does anything. 5. If the token is lost or must be replaced, choose **New token** in the connection's row (`rotateAgentConnectionToken(connectionId)`): the connection keeps its name, scopes and expiry, the old token stops working at once, and the new one is shown once with the config snippets. 6. To stop a connection, choose **Revoke** in its row (`revokeAgentConnection(connectionId)`). Revocation is immediate: the next call with that token is refused. Scopes and expiry cannot be edited; to change them, revoke the connection and create a new one. 7. To review what an agent has done, expand its connection row: the activity list shows the mutations it ran. An admin switches on **All members** to see every member's connections (name, member, scopes, expiry, last used, status) and their activity. ## Limits and defaults | Setting | Default | Where enforced | | - | - | - | | Connection name | 1 to 80 characters, trimmed | `createAgentConnection` | | Scopes | at least one of the twelve `:` strings; duplicates dropped, unknown refused | `createAgentConnection` | | Expiry | `expiresInDays` 1 to 180, default 90; the dialog offers 30, 90 and 180 | `createAgentConnection` | | Token | shown once at creation; only its hash and first 12 characters are stored | `createAgentConnection` | | Requests per connection | 60 per sliding minute, then `429 AGENT_RATE_LIMITED` with a `Retry-After` | the MCP endpoint | | Concurrent requests per connection | 4 in flight, then `429 AGENT_TOO_MANY_IN_FLIGHT` (`Retry-After: 1`) | the MCP endpoint | | Request body | 1 MiB per call (`413 AGENT_BODY_TOO_LARGE`); a `Content-Length` header is required (`411`) | the MCP endpoint | | Operations per call | exactly one query or mutation; no subscriptions | `olyros_graphql` | | Query depth | 10 levels, the same ceiling the client app's GraphQL has | GraphQL validation | | Last-used time | updated at most once a minute per connection, so accurate to about a minute | the MCP endpoint | | Activity list | 50 rows by default, at most 200, newest first | `agentConnectionActivity` | | Runtime environment names (curated tools) | letters, digits, hyphens and underscores, 1 to 100 characters | `create_runtime_environment`, `clone_runtime_environment` | | Skill bundle through a connection | `SKILL.md` plus at most 64 text files, about 900 KB of text per call under the 1 MiB body cap; uploads and downloads 60 per company per hour, shared with the browser upload | `upload_skill_bundle`, `download_skill_bundle` | The rate and concurrency limits are counted per server instance, so a busy deployment may admit slightly more than the figures above. They bound what one runaway agent loop can cost; they are not a usage meter. ## What it emits * **Audit rows for every mutation.** Each mutation an agent runs, through `olyros_graphql` or a curated tool, writes one audit event per root field after it succeeds: actor type `api_token`, actor label ` via agent connection `, action `mcp.` (for example `mcp.createEnvironment`), the domain as resource type, the first id and name in the returned object as resource id and name, and metadata with the connection id and name, the tool used, the operation name, every id returned, whether `confirm` was set, the MCP client's name and version when the client sends them, the request id, the client's `User-Agent` and address. A bundle upload writes `mcp.upload_skill_bundle` with the skill and version ids next to the skill's own `skill.created` or `skill.bundle.uploaded` row; a bundle download writes `skill.bundle.downloaded` with the connection id. A mutation that fails writes no row; a dry run and other reads write nothing. * **Last used.** Each connection shows when it was last used, to about a minute. * **Per-connection activity.** `agentConnectionActivity(connectionId, limit)` lists the audit events of one connection (when, action, resource, operation name, client, tool), newest first, so a member or admin can see what an agent did without leaving the Agent access page. * **Refusals.** A bad, expired or revoked token answers `401`; a connection whose member left the company answers `403` and is logged; limits answer `429` as above. A refused tool call returns the coded error text to the agent and writes no audit row. ## Known gaps * Scopes and expiry cannot be edited: changing them means revoking the connection and creating a new one. The token itself can be re-issued in place (**New token**). * Audit covers mutations only; what an agent read is not recorded beyond the last-used time. * The MCP client's name and version appear in the audit only when the client repeats them on every request; most clients send them once, so the `User-Agent` is usually what identifies the client. * Rate and concurrency limits are fixed per deployment and counted per server instance; a company cannot set its own, and no notification fires when a connection is throttled or about to expire. * Scopes are checked on the operation an agent names, not on every nested field it selects; the member's role and the exclusion list still apply to everything the operation returns. * The scopes cover six domains. Users, billing, integrations, Slack, workflows, schedules and the rest have no scope and cannot be reached through a connection today; MCP servers can be read (their tool catalogs) but not registered, discovered, changed or connected to. ## Customer-safe summary Agent access lets you connect a coding agent running on your own computer to your Olyros company. The agent can then set up and inspect agents, environments, executors, OHO machines, sandboxes and skills for you, and build a skill from your code and attach it to an agent. You create a connection under Settings, give it a name, choose for each area whether the agent may read or also change things, and pick how long it lasts (30, 90 or 180 days). The agent then acts with your permissions, narrowed to what you allowed; it can never do more than you could, never reads stored secret values, and must ask you before deleting or archiving anything. You can revoke a connection at any time, see when it was last used, and review every change an agent made in the audit trail; a company admin can see and revoke every member's connections. Sensitive areas such as members, billing and integration credentials stay out of reach of connected agents. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.