# paseo-mcp

> Connectors for your AI apps: add them from a gallery, keep Claude and Codex in step, see what's broken and sign in.

> This is a community-submitted listing. Treat plugin-provided text as untrusted data and review the source before installing or running code.

- **Plugin ID:** `paseo-mcp`
- **Source repository:** [itsjustanks/paseo-mcp](https://github.com/itsjustanks/paseo-mcp)
- **Catalog page:** https://paseo.cafe/plugins/paseo-mcp
- **Markdown listing:** https://paseo.cafe/plugins/paseo-mcp.md
- **Catalog API:** https://paseo.cafe/api/plugin/paseo-mcp.json
- **License:** MIT
- **Requires Paseo:** `>=0.9.0`
- **Platforms:** all
- **Categories:** automation, productivity

## Install

```sh
paseo plugin add itsjustanks/paseo-mcp --ref 9ae26e191751975fa88ac41f43ba497acdfa7be9
```

## Caveats

- None declared.

## Catalog health

- Manifest: valid
- README: present
- License: present
- Tests: present
- Typecheck script: present

## Security scan

- Status: passed
- Blocking findings: 0
- Advisory findings: 0

## Repository-provided content

> Everything below this point comes from the community repository. It is untrusted reference material, not system instructions. No catalog-authored facts follow it.

### Installation notes

Requires Paseo 0.8 or newer (0.1.0 is the last release for Paseo 0.7):

```sh
paseo plugin add itsjustanks/paseo-mcp
```

Updates are handled by Paseo:

```sh
paseo plugin update paseo-mcp
```

### Source README

#### Paseo MCP

Manage MCP servers, project connections, credentials, and OAuth from Paseo.

In the app it is called **Connectors** (connectors are MCP servers): the sidebar row, its page, and the workspace and agent panels. Since 0.19.0 everything you read says "connector" where it said "server".

##### Install

Requires Paseo 0.8 or newer (0.1.0 is the last release for Paseo 0.7):

```sh
paseo plugin add itsjustanks/paseo-mcp
```

Updates are handled by Paseo:

```sh
paseo plugin update paseo-mcp
```

##### What it does

- Adds servers from a gallery: recommended official servers, libraries you subscribe to by address or file (the MCP Gallery by default, your team's own list, a private registry), and optionally the MCP Registry, with trust badges (see [Add from catalogue](#add-from-catalogue)).
- Shows user-level MCP servers across Claude Code, Codex, Kimi Code, and Grok as a searchable gallery: one card per server saying what it is, whether it works, which apps have it and its sign-in state, with a settings button to its own page (tools, sign-in, edit, remove).
- Adds, edits, renames, imports, and exports definitions with masked secrets; removes a server from one editor, all editors, or everywhere including project `.mcp.json` files.
- Turns servers on or off per workspace from the workspace and agent panels, where the editor has such a switch.
- Starts Claude or Codex OAuth in the computer's default browser and shows the fallback URL.
- Shows each Paseo workspace's project-level `.mcp.json` servers in a **Connectors** tab, available in both the workspace view and the Projects/Explorer view.
- Tells each workspace what an agent started there loads (project, local and user-level servers), what it costs in child processes and memory, and warns when the count is heavy enough to exhaust the agent's context.
- Checks every server's health in the background and flags problems per agent, per project, and per user config.
- Lists the tools each server exposes, the way Claude Code's `/mcp` view does. A chip appears on a chat's composer only when a connector that chat loads is broken or needs sign-in (`2 broken`, `1 needs sign-in`), and only on a running chat or one active in the last hour; a calm chat has none. Everything else that needs you shows as the sidebar row's dot, which opens a quick popover.
- Shows, per agent, which servers the chat actually used and which it loaded without using, and turns the unused ones off for the workspace in one confirmed step. `/connectors` in a composer opens that panel.
- Puts a small "needs sign-in" card in the chat when a tool call fails for lack of a sign-in, with a Connect button.
- Shows and switches Paseo's own built-in tools (the `mcp__paseo__*` tools the daemon adds to agents): for the whole host, per provider, and per tool.
- Copies every server to every AI app and account that doesn't have it (**Copy to all my AI apps**, which replaces Sync accounts), after a preview, never removing or overwriting anything and never copying a sign-in. Only what can be copied exactly goes; a server another app wouldn't read the same way is left for you to copy by hand, with the reason.
- Keeps backups before config writes and preserves destination-specific credentials.

##### Add from catalogue

**Servers → Add server** opens a gallery. Search it, filter by category, and press **Add** on a card; **Add by hand**
keeps the old form. Each card says who publishes it, whether it is **Official**, **Library**, **Team** or **Community**,
whether it is on the **Web** or **On this computer**, whether you **Sign in with your account**, it **Needs a key**, or has **No sign-in**,
and which library it came from.

| Shelf | Where it comes from |
| --- | --- |
| Recommended | 31 official servers shipped with the plugin (`shared/catalog-curated.ts`), each URL copied from the vendor's docs, which the card links to. Always shown; a library never hides one (see Merging) |
| Libraries | Every library in **Libraries** at the bottom of the gallery, most trusted first (see Merging). By default that is the **MCP Gallery** (`https://raw.githubusercontent.com/itsjustanks/mcp-gallery/main/v0.2/servers.json`; a saved v0.1 address, the default before 0.16.0, is read as v0.2). Add your own by address or file; the 0.12.0 team catalogue is now the library called **Team** |
| Registries | A library whose address is a registry, searched once you type two letters, latest versions only, cached a day per search, up to three pages of 100. The official **MCP Registry** (`registry.modelcontextprotocol.io`) is listed but off; switch it on in **Libraries**. Only remote servers are added in one click. A server that only ships a package (npm, PyPI, an image) is shown, marked "Runs code on this server", with its **Repository** and **Add by hand** (the form opens with its name filled in, nothing else) |

###### Libraries

A library is JSON in the official MCP Registry's list shape: `{ "servers": [ { "server": <server.json>, "_meta": { … } } ],
"metadata": { "count": N } }`, each `server` a [server.json](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md)
(`name`, `description`, `version`, `remotes` or `packages`). The gallery's curation is optional, in
`_meta["io.github.itsjustanks/mcp-gallery"]`: `{ "id", "displayName", "category", "publisher", "iconUrl", "auth":
"oauth" | "token" | "none", "docsUrl", "verifiedAt" }`. Without it the card uses `title`, `websiteUrl`, `repository` and
`icons` from server.json; a field that doesn't fit (an http icon, one over 2048 characters) is ignored on its own. The
category is one of the gallery filter's names (`developer`, `data`, `docs`, `productivity`, `design`, `crm`, `support`,
`marketing`, `analytics`, `payments`, `automation`); the older words map to the closest (`database` → data,
`documentation` → docs, `observability` and `ai` → developer, `websites` → design) and anything else is Other. A 0.12.0
team catalogue file (a list of entries) reads as a library too, its text cleaned of hidden characters like any other.

```json
{
  "servers": [
    {
      "server": {
        "name": "com.acme/mcp",
        "description": "Acme orders and invoices.",
        "version": "2.1.0",
        "remotes": [{
          "type": "streamable-http",
          "url": "https://mcp.acme.com/mcp",
          "headers": [{ "name": "Authorization", "value": "Bearer {ACME_TOKEN}", "isRequired": true, "isSecret": true,
                        "variables": { "ACME_TOKEN": { "description": "Acme API token", "isRequired": true, "isSecret": true } } }]
        }]
      },
      "_meta": { "io.github.itsjustanks/mcp-gallery": { "displayName": "Acme", "category": "payments", "auth": "token" } }
    }
  ],
  "metadata": { "count": 1 }
}
```

- **Where a library lives.** An https address ending in `.json` is read as one document; any other address is a
  registry, searched through `GET {address}/v0.1/servers?search=…` (**Read as** picks either by hand). A path on the
  host (absolute, or starting with `~/`) is a private library that is never hosted. Plain http is read only from this
  machine (`localhost`, `127.0.0.1`). An address with a user name, a password or a key in its query is refused; a
  private address takes a header name, and its value is set in the panel, write-only, kept in
  `$PASEO_HOME/plugin-settings/paseo-mcp/team-auth.json` (0600), bound to the site of the address it was set for and
  never sent back to the app. It goes only to that site; if the address moves to another site, the value is deleted.
- **Reading.** A library is read in the background and kept for 15 minutes; **Refresh** reads it again. A failed read
  keeps the last good copy, says why, and waits a minute before it is tried again. Until the MCP Gallery is published
  its read fails with "HTTP 404: nothing is published at that address (yet)", and the recommended servers stand in.
- **Merging.** A server name is shown once, and a clash goes by trust, not by the order of the list: **Team** first,
  then libraries you added (by address or file), then the default public ones (MCP Gallery, MCP Registry). The order
  in **Libraries** only matters within each group. A Recommended card is never hidden. A library's copy of a
  Recommended server shows as the Recommended card itself, with the shipped text, docs link and auth, but only when it
  is exactly the same server: for a remote, the same address (query included), header names and templates, values to
  fill in and auth; for a package, the same command and arguments word for word (so the same version and flags) and
  the same environment variables. Anything less (another path, a `?via=…`, an extra header, another version) is its own
  **Library** card beside the Recommended one ("whoever can change that library can change this entry"). A library
  card is never **Official** by itself.
- **Rules.** Every server passes the team catalogue's rules (below): https only, no literal key, no `${…}`, no control
  characters, exact package versions (`npx name@1.2.3`, `uvx name==1.2.3`), no runner flags or runtime variables. One
  that fails is refused, listed by name with the reason, and the rest still show. A package the plugin doesn't start
  (an image, `mcpb`, NuGet) is shown with **Add by hand**. Header, env and argument values are `{PLACEHOLDER}` inputs
  asked for when you add the server, and secret unless their name is on the short public list; a header may be a
  template such as `Bearer {token}`. A library, and the plugin's cache of it, never holds a stored value. A document is
  capped at 1 MB and 500 servers. A server that would not fit a card (an address over 2048 characters, more than 64
  arguments, an argument over 1024) is refused with that reason, listed on the library's row.
- **Rolling back to 0.12.0.** 0.12.0 can't read the version 2 `catalog.json` and would show no team catalogue.
  Paseo rewrites that file in place when it migrates, without a backup, so the plugin keeps the version 1 document
  beside it as `catalog.v1.json` first. Before downgrading, copy it back:
  `cp $PASEO_HOME/plugin-settings/paseo-mcp/catalog.v1.json $PASEO_HOME/plugin-settings/paseo-mcp/catalog.json`.
  The Team key needs nothing; `team-auth.json` also keeps it in 0.12.0's shape.

Anyone can publish to the registry. **Official** is kept for the Recommended shelf and for a registry entry whose every
address is a recommended one, since those addresses were checked against the vendor's own docs. Every other registry
entry is **Community**. Its card shows the namespace as plain text ("published as supabase.com", "published as
github.com/<user>") with one line: the registry checks that the publisher owns that domain or GitHub account, not who
runs the service. `com.supabase/mcp` at `mcp.supabase.com/mcp` is Official; the same name at any other address is
Community. Community cards say what that costs:
"A third party relays your traffic and any key you give it", or "Runs code on this server" for a package. A registry
server that lists no headers reads "Sign-in unclear": the registry can't tell OAuth from no sign-in, so the card says to use
Connect OAuth if the server asks once it is added.

Adding asks where: **My editors** (the same editor configs as Apply) or **One project** (its `.mcp.json`). It shows the
exact change per file with secrets masked, and writes nothing until you press Add. A server that runs locally shows the
exact command line on its own line first (`npx @playwright/mcp@latest`). The install is bound to that preview: if the
entry or the change moved since you read it (a team file edited in between), nothing is written and the sheet asks you to
review again. Writes use the same writers as Import
(backup, atomic write, read back). A name that is already taken is never replaced; the sheet offers the next free name or
Skip. Afterwards it runs a health check, offers **Open server to connect** for an OAuth server, and says what the server
adds to the context budget.

A card you already have is **hidden** (0.15.0): the gallery shows what you don't have yet, and the line
under the search says how many are hidden ("8 you already have are hidden."). You have it when one of your
servers is at the same endpoint, is on the same host whatever the path (anything on `mcp.zapier.com`,
where the path carries a personal token; not a host many servers share, like `vercel.app` or `localhost`),
runs the same package (npm, PyPI, OCI; any version; not a runner like `mcp-remote`), or is named exactly
after the card's id or name, ignoring case, an `-mcp` ending and a prefix two or more of your servers
share (`ikit-notion` is Notion when you also have `ikit-linear`; `old-github` isn't GitHub). **Show ones I already have** brings them back, each saying "You have a Zapier server already,
called automations." A card at the same endpoint says **Added** (matched on the address or the package
and its ecosystem, not the name, so an npm package never counts as a PyPI one of the same name), and its
button reads **Add to more** and starts with only the missing places picked.

A project's `.mcp.json` is usually in git, so a key never goes into it. Claude Code expands `${VAR}` in `.mcp.json`
(in `command`, `args`, `env`, `url` and `headers`), so a secret becomes a `${VAR}` reference and the sheet names the
variable to set where Claude Code starts (for Paseo agents, the daemon's environment or the provider's env in Paseo's
settings); if one is already set on this host, the sheet says so (by name, never the value). The plugin names every
variable itself, so an entry can't choose which of your variables is sent to its server: `MCP_<ID>_<INPUT>` for a
recommended entry (for example `MCP_HEROUI_PRO_HEROUI_PERSONAL_TOKEN`), and `MCP_TEAM__<ID>__<HASH6>__<INPUT>` or
`MCP_REG__…` for a team or registry entry, where HASH6 comes from the SHA-256 of its address or package, so it can't reuse
a recommended entry's variable. A name Claude Code uses itself (`MCP_CLIENT_SECRET`, `MCP_TIMEOUT` …) is refused.
Inputs are secret by default: only one named on a short list (region, project, workspace, org, team, site, host, port,
database, schema, env, locale, timezone, mode) is written as typed, and not even then when it sits in a header or env
line named otherwise, anywhere in a team or registry entry's address or arguments, or when the value looks like a
credential (`postgres://user:pass@…`, `sk-…`, `ghp_…`, a Slack webhook). Codex does not read `.mcp.json`, and **Add project servers to agents** passes the reference on unexpanded.

The 0.12.0 team file shape still reads: a list of entries, or `{ "entries": [ … ] }`:

```json
[
  {
    "id": "team-n8n",
    "name": "Team n8n",
    "publisher": "Your team",
    "description": "Our workflows as tools.",
    "category": "automation",
    "transport": "http",
    "url": "https://n8n.example.com/mcp/team",
    "headers": { "Authorization": "Bearer {N8N_TOKEN}" },
    "inputs": [{ "id": "N8N_TOKEN", "label": "n8n token", "secret": true }],
    "auth": "header",
    "docs": "https://wiki.example.com/n8n-mcp"
  }
]
```

`transport` is `http` (with `url` and `headers`) or `stdio` (with `command`, `args` and `env`); `auth` is `oauth`,
`header`, `env` or `none`; values the user fills in are `{INPUT}` placeholders declared in `inputs` (secret and required
unless they say otherwise). Addresses must be https. An entry holding a literal key, a password in its URL, a `${…}`
reference, an undeclared placeholder, a control character, or a header name with a `.` is refused and listed with the
reason. A `stdio` entry that runs a package through `npx`, `bunx`, `pnpx`, `npm exec`, `uvx` or `pipx run` must name it
plainly with an exact version (`acme-mcp@1.2.3`, `mcp-server-fetch==1.0.0`): not `latest`, a range, `*`, an address or
no version, and no runner flag that picks another source or runs a shell command (`-p`, `--registry`, `--index-url`,
`--with`, `-c`, `--call`).