Skills & MCP servers

Two ways to equip every run at once: instructions the agent reads, and tools it can call.

A skill is written in a project — one every project should be able to use, in a shared project — and an MCP server is registered once for the organization, because it holds the organization's token. Each is then picked per project, by someone with Manage workflows.

• A skill is a page of instructions with one line saying when it applies. The agent always sees that line; when the work matches, it reads the page and follows it. "How we write commit messages", "our review tone", "the deploy checklist" — the things you would brief a new teammate on.
• An MCP server is an outside service the agent may call tools on during a run — a docs index, a database gateway, an internal API. Anything that speaks the Model Context Protocol.

This is the opposite direction from Connected apps: that page is about chat apps driving Peractor; this one is about a run's agent reaching somebody else's tools.

Skills

Write one under the project's Settings → Skills: a name, the "when it applies" line, and the instructions in markdown. Skills use the open SKILL.md format, which buys two things:

• Any public skill works here. Paste its address — the repository URL, a folder inside it, or a link to the SKILL.md itself — and Peractor fetches its SKILL.md as a draft for you to read and save. The empty screen suggests a few well-known ones to start from.
• They work on every agent. Claude Code discovers staged skills natively; agents without a scanner get the same skills listed in their instructions, with the files on disk beside the work.

During a run, each picked skill is staged read-only into the workspace and excluded from git, so it can never be committed.

MCP servers

Register one under Settings → MCP servers: a name, how it is reached — a URL, or a command that runs beside the agent inside the sandbox — and where its token goes, or that somebody signs in to it instead. Both built-in agents get every picked server on every prompt step, each configured in its own format.

The token is write-only. It is encrypted the moment you save it and never shown again.

• A server reached by a URL never hands a run its token. The run's agent reaches it through Peractor. Each call is checked against the projects and the tools below, made with the token on Peractor's side, and kept in the audit log, so nothing inside the run can read the token or carry it off.
• A server that runs as a command runs inside the sandbox, beside the agent, so the run's environment carries its token. Its page says so and lists no tools to set: the agent can call whatever it offers.

Registering or changing a server takes Manage workflows and lands in the organization's audit log. Which projects may use it, and what a run may do with each of its tools, take Manage connectors. Register only services you trust.

Which projects may use it

An organization's server has Projects: All projects, or Only these with a tick for each. A project that isn't on the list can't pick the server, and its runs stop getting it even if it was picked before. Each project says what it takes from the server, so taking one off tells you what stops first.

A new organization server starts with no project. Registering one asks Which projects may use it?, with nothing chosen, if you hold Manage connectors. Without it you can still register the server, and it waits for somebody who holds it to choose. That holds however the server is made — in Settings, by the assistant, through MCP or the public API. A server registered before this existed keeps every project until somebody changes its Projects.

What a run may do with each tool

The server's Tools list each tool it offers, with one of three settings:

• Live: the agent's call goes through at once.
• Waits for a person: the call doesn't happen. The agent is told it waits, and the phase ends on a review of what it held (see Runs).
• Off: the agent is never offered it.

A tool the server marks read-only starts Live. Every other tool starts waiting until somebody with Manage connectors says otherwise.

Servers you sign in to

Many hosted servers — Google Workspace's, Microsoft 365's, and most others that hold your work — take no token you can paste. They ask you to sign in. For those, set The server expects to A sign-in (OAuth), then press Connect in the server's Sign-in block. The service's own sign-in page opens; once you approve it, come back to Settings and the block says you are signed in.

• It is the organization's sign-in. Whoever signs in, every run that carries the server, and the assistant, reaches it as them, the way a pasted token would. Signing in takes Manage workflows, like the server itself, and both signing in and out land in the audit log.
• Peractor keeps it and renews it. The sign-in is stored encrypted and never shown, and renewed before each call, so a long step keeps the server however long it runs.
• Some services need a client ID. Peractor registers itself with a service when the service allows it. Google and Microsoft don't: register Peractor in their developer console, give it the redirect URI the Sign-in block shows, and enter the Client ID (and the client secret, if it gives one) in the server's settings. Scopes is optional; left empty, Peractor asks for what the server asks for.
• It is tied to the server's address. Change the URL and the sign-in, and any client secret, stop being sent — sign in again for the new address.

Once signed in, the server is one of the assistant's services like any other. Until somebody signs in, the assistant can't use it, and it offers the server's Connect on a card instead — the same card you get when you ask it to sign a server in. It can sign one out too. A Peractor whose secrets live in its own environment rather than its encrypted store can't keep a sign-in, and says so.

The assistant uses them too. A conversation reaches the same servers a run in its project would, and an organization's whole list for the people who manage it. A lookup runs at once; a tool that would change something waits as a step of the assistant's plan — see The assistant. Only servers reached by a URL work there.

Picking is the boundary

Like shared workflows and instructions, nothing a shared project or the organization offers reaches any run until a project ticks it, under that project's Settings → Shared library. Stop picking a skill or server and it stops applying on the next run — nothing needs restarting.