Skip to content

Add a connector from the registry

You can find a connector (an MCP server) on a registry, GitHub's by default, the official MCP Registry, or one you added (see Choose marketplaces), and add it without leaving the app, either for yourself, so every agent you start has it, or to one project. The app shows the command or URL before anything is written. A secret is stored as ${NAME} in mcp.json, and the value goes in your own ~/.agents-secrets/secrets.env, which is never committed and never shown again.

Before you start

  • The registry is open. Nothing else is needed. If it cannot be reached, the sheet says so and adds nothing.

Add a connector for yourself

  1. Open Settings ▸ Agent Configuration ▸ Connectors and choose Add Connector…. The connectors that Agents makes come first, under Made by Agents: GitHub and Linear. They run hosted, one copy for each host, so their events come in when no agent runs.
  2. Type what you are looking for. Results come from the marketplace chosen in the Marketplace menu, in its own order (GitHub's puts the most starred first). Each shows the publisher it has checked (a GitHub org, or a domain), the description, the version, and how the server runs. known marks a publisher on the app's short list. A remote that runs on someone else's host names that host. Each row also shows the five levels the connector reaches: Tools, Events, Views, Workflows and Tested. A level that is not reached is grey. A connector from a registry shows its levels after its host checks it. See Integrations for what each level means.
  3. Choose one. The sheet shows the command, with the version pinned, or the URL, each variable, and the entry that will be written, with ${NAME} where a secret goes. Where there is more than one way to run it, Run with chooses, and the rest follows.
  4. Fill each required secret. Add stays unavailable until every one has a value, or is already set. One that is already in secrets.env says so, and you can leave it or replace it.
  5. Choose Add. The entry goes into ~/.agents/mcp.json. The value goes into ~/.agents-secrets/secrets.env, created if it is missing, and readable only by you. The next agent you start has the connector, with the name filled in.

Add a connector to a project

  1. Open the project. Its page has a Connectors section, after Skills and before Plugins, listing what is in the project's .agents/mcp.json. The line under the heading says the file is committed with the project, and that it names secrets rather than holding them: each person sets their own.
  2. Choose Add Connector… there. The sheet is aimed at the project.
  3. Search and add as above. The entry goes into <project>/.agents/mcp.json with only ${NAME} in it. The value still goes into your ~/.agents-secrets/secrets.env, not the project.

A connector added from the sheet is approved as it goes in. One that arrives with a pull is listed as waiting for your OK, with the command it runs, and no agent is given it until you choose Approve. If it changes after that, it waits again.

Where you and the project both have a server of the same name, agents in that project get the project's. A project on a server does not show this section.

A secret that is not set

The row names it, as NAME not set, and offers Set…. Settings ▸ Agent Configuration strikes that server's reach and lists it under Needs a look. Agents start without the server, rather than with an empty key. Replace… changes a value that is already set. Either way the new value is not shown again.

Take a connector out

Remove… is offered only for a connector the app added. One from the registry shows registry and the version it was added at; one added on the sheet by hand shows added by hand (see Add a connector by hand). Confirming takes the entry out of mcp.json. The secret stays in secrets.env unless nothing else names it, in which case you can tick Also forget that name. If another server still names it, the secret stays and the sheet says so.

A server you wrote into mcp.json yourself has no Remove. If its name is the one you wanted to add, the app leaves it alone.

A connector that is not on the registry can be added from the same sheet with Add by hand…, which connects to it before anything is written: see Add a connector by hand.

If mcp.json cannot be read, Add is refused and the file is not written.