mcp-registry
The gateway can front a Gitea MCP server, making its tools available through the unified MCP endpoint and calling them with the person's credentials or a shared server secret.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-registry
A self-hosted MCP gateway: one MCP endpoint for your AI agents (Claude Code and other MCP clients) in front of all the MCP servers your team uses.
Quick start
You need Docker with Compose. Run this in an empty directory. Compose also reads a .env file from the directory it runs in, so settings left there by another project would apply.
curl -fsSL https://raw.githubusercontent.com/ai-pipes/mcp-registry/v1.0.0/quickstart.compose.yml | docker compose -f - up -dThis starts the gateway and Postgres with no .env and no identity provider. The secrets key and the database password are generated into a Docker volume, and the port is published on 127.0.0.1 only, so the gateway is reachable from this machine at http://localhost:3000. On a remote machine, forward the port with ssh -L 3000:localhost:3000 <host> and open the link on your own machine; it works as is, because PUBLIC_URL is http://localhost:3000. To expose the gateway for real, see Production setup.
On the first start the gateway creates the admin local-admin and logs a one-time sign-in link. Print it:
docker compose -p mcp-registry logs app | grep "one-time link"If it prints nothing, wait a few seconds and run it again: the link is logged after the database migrations.
The link is in the url field of the log record and looks like http://localhost:3000/login#link=ll_.... Open it within 15 minutes; the page asks for one click on Sign in with the link, then you are signed in as an admin. The link works once.
Port 3000 is taken. Set
PORTon thedocker composeside of the command, for example:curl -fsSL https://raw.githubusercontent.com/ai-pipes/mcp-registry/v1.0.0/quickstart.compose.yml | PORT=8080 docker compose -f - up -dThe sign-in link then points to that port. Settings are not remembered between commands: repeat
PORTwhenever you runupagain.Safari does not accept the
Securesession cookie on plainhttp://localhost. Use another browser, or start withCOOKIE_SECURE=false(same place asPORT).A new link, if the first one expired or was used by mistake:
docker compose -p mcp-registry exec app node dist/cli.js login-link local-adminUntil
local-adminhas signed in once, every start also logs a new link.
To stop the gateway, run docker compose -p mcp-registry down; your data stays in the volumes, and running the quick-start command again starts it with the same data. docker compose -p mcp-registry down -v also deletes the volumes: the database and the generated secrets key are gone for good.
The quick start is for trying the gateway and for a single machine. For a permanent installation behind HTTPS with your own identity provider, see Production setup.
Related MCP server: MCP-ToolHub
Add your first server
The example uses DeepWiki, a public MCP server for questions about GitHub repositories. It needs no key. It is a third-party service: the questions your agent asks through it are sent to that server and leave your machine. Any other MCP server that speaks Streamable HTTP is added the same way (see Adding upstream servers for the ones that need credentials).
In the web UI, open Servers under Administration and press Add server.
Fill in the form. The slug is the prefix of the tool names (
deepwiki.ask_wiki_question) and cannot be changed later.Field
Value
Slug
deepwikiName
DeepWikiDescription
Documentation and Q&A for public GitHub repositoriesURL
https://mcp.deepwiki.com/mcpAuthorization
No authorization
Access
Everyone
Leave the call timeout and the daily limit as they are, and press Save.
The gateway creates the server and reads its tools at once. The server page lists them, and Catalog shows the same three as of writing:
deepwiki.ask_wiki_question,deepwiki.read_wiki_contentsanddeepwiki.read_wiki_structure. If no tools appear, the server page shows the Last sync error; fix the cause (for example the URL) and press Sync now. The gateway then re-reads this server's tool list on its sync schedule (every 6 hours by default) until the server is disabled.


Connect an agent
Open Tokens, press Create token, give it a name such as
laptop, press Create and copy the command from the dialog. The token is shown once.Run the command. It registers the gateway in Claude Code:
claude mcp add --transport http mcp-registry http://localhost:3000/mcp \ --header "Authorization: Bearer sk_..."Claude Code registers it for the current directory only: start
claudein the same directory, or add--scope userto the command to make the gateway available in every project.

Other MCP clients work the same way: the endpoint is <your URL>/mcp and the token goes in an Authorization: Bearer header. The agent sees four tools, whatever the catalog holds: list_servers, search_tools, describe_tool and call_tool (see How it works).
Now ask the agent something that needs the server:
Using the gateway, ask DeepWiki how routing works in the
honojs/honorepository.
The agent typically makes three calls (it may call list_servers first):
search_toolswith a short description such as "ask a question about a GitHub repository". It returnsdeepwiki.ask_wiki_questionfirst.describe_toolfordeepwiki.ask_wiki_question, which returns its description and input schema (repoNameandquestion).call_toolfordeepwiki.ask_wiki_questionwithrepoNamehonojs/honoand the question. The gateway forwards the call to DeepWiki and returns its answer unchanged.
The call log in Call log (admins) shows who called which tool, the outcome and the duration, never the arguments or the results.
About
Instead of loading hundreds of upstream tools into the agent's context, the gateway exposes four meta-tools. The agent searches for the tool it needs, reads its schema, and calls it through the gateway. Each call is made on behalf of the person: with their own OAuth token or personal access token for that service, or with a shared server secret that never leaves the gateway.
Who it is for. Individuals and small teams who run their own services (Gitea, YouTrack, internal tools) inside their own network and want one place to manage MCP access. It is a single container plus Postgres. It is not an enterprise product: no multi-tenancy, no HA clustering, no fine-grained RBAC beyond "member / admin / server visible to groups".
How it works
flowchart LR
A[Claude Code<br/>Bearer sk_...] -->|/mcp| G[mcp-registry]
B[Browser] -->|OIDC or<br/>one-time link| G
G -->|person's OAuth token / PAT<br/>or shared secret| U1[Gitea MCP]
G --> U2[YouTrack MCP]
G --> U3[Other MCP servers]
G --- DB[(Postgres + pgvector)]The agent sees exactly four tools, whatever the catalog contains:
Tool | What it does |
| Servers the person may use, and whether they still need to connect an account (with a link). |
| Hybrid search (full-text + vector) over tool descriptions; returns |
| Full description and |
| Calls the upstream tool with the person's credentials; the upstream result is returned as is. |
Search returns an empty list when nothing is relevant enough, rather than padding results with near misses.
Features
UI login through any OIDC provider that can put the person's groups or roles into a claim of the ID token or UserInfo, or, with no provider, through one-time sign-in links; no passwords stored.
Personal API tokens (
sk_...) for/mcp; the UI shows a ready-to-pasteclaude mcp addcommand.Server catalog: add upstream MCP servers, restrict them to groups, hide individual tools, set per-call timeouts and per-person daily limits.
Per-user credentials: OAuth 2.0 (Authorization Code + PKCE, automatic refresh) or personal access tokens; or one shared secret per server.
Secrets encrypted at rest with AES-256-GCM; key rotation without downtime.
Catalog synchronisation with upstream every 6 hours (configurable) and on demand.
Local embeddings (
multilingual-e5-small, baked into the image; no external service, works offline). An OpenAI-compatible embeddings API can be used instead.Call log (who, which tool, outcome, duration; never arguments or results), audit log of admin actions.
Strict CSP web UI (
default-src 'self', no inline scripts or styles).
Production setup
This is the permanent installation: your own .env, a TLS-terminating reverse proxy and, if you want, your own OIDC provider. Plan upgrades with Versioning and upgrades, and read SECURITY.md before exposing the gateway beyond localhost. The quickstart.compose.yml file can also be saved and kept as a permanent installation; see its header comment and SECURITY.md.
Requirements: Docker with Compose, and (for anything beyond localhost) a TLS-terminating reverse proxy in front of the gateway.
git clone https://github.com/ai-pipes/mcp-registry.git && cd mcp-registry
cp .env.example .envEdit .env:
PUBLIC_URL=https://mcp.example.com
TRUST_PROXY=true # behind a reverse proxy
POSTGRES_PASSWORD=$(openssl rand -base64 32)
SECRETS_KEY=$(openssl rand -base64 32) # back this up: without it stored secrets are lost
# Optional: sign in through your OIDC provider. Set all three or none (see "First admin").
OIDC_ISSUER=https://id.example.com
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...(Generate the values with openssl rand -base64 32 and paste them in; .env does not run shell commands.)
Start it:
docker compose up -d --build
curl http://localhost:3000/healthz # okCompose runs the app and pgvector/pgvector:pg17; Postgres is not published. Migrations run on startup. A prebuilt image is published to ghcr.io/ai-pipes/mcp-registry for tagged releases.
First admin
With OIDC (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET set): put yourself in the admin group of your provider (OIDC_ADMIN_GROUP, default mcp-admins) and sign in at PUBLIC_URL. Role and groups are taken from the provider on every login.
Without OIDC (none of the three set): on the first start the server creates the admin local-admin and logs a one-time sign-in link. Open it within 15 minutes:
docker compose logs app | grep "one-time link" # the link is in the "url" fieldThe link looks like https://mcp.example.com/login#link=ll_...; it works once. The page asks for one confirmation click before it signs you in. The link is logged at warn level, so with LOG_LEVEL set to error or stricter use login-link local-admin instead. Until local-admin has signed in, every start logs a new link (each invalidates the previous one). To sign in again, or to let another person in, print a link with the CLI; <sub> is the person's subject ID (for create-user, any name you choose):
docker compose exec app node dist/cli.js create-user --sub jane --name "Jane" # new person; add --admin for an admin
docker compose exec app node dist/cli.js login-link janelogin-link also works with OIDC configured (emergency access). Links are valid for 15 minutes and a person has at most one live link. Anyone who can read the container log right after the first start can use the link, so see SECURITY.md. Without OIDC there is no group management: admins see every active server, members see servers open to everyone or to the login group. To move to OIDC later, see SECURITY.md.
With OIDC you can also create a person with the CLI, for example when the provider is down. <sub> is the person's subject ID at the provider:
docker compose exec app node dist/cli.js create-user --sub <sub> --name "Jane" --adminTokens for agents
In the UI, open Tokens, create a token and copy the command it shows. Or from the CLI:
docker compose exec app node dist/cli.js create-token <sub> --name laptopThen:
claude mcp add --transport http mcp-registry https://mcp.example.com/mcp \
--header "Authorization: Bearer sk_..."Configuration
All settings are environment variables (see .env.example). An empty value (KEY=) counts as unset.
Variable | Default | Meaning |
| required | External URL of the gateway (scheme + host + port). Used for OIDC/OAuth redirect URIs, the |
| required (Compose sets it) | Postgres connection string. Compose defaults to |
| required by Compose | Password of the bundled Postgres. Set it before the first start; it is stored in the volume afterwards. |
|
| Listening port (with Compose: the host port; the container always listens on 3000). |
|
| Host address the port is published on. |
| empty | Extra accepted |
|
| Take the client IP from |
|
| Number of trusted proxies in front of the gateway (1-5). |
|
|
|
| required unless | AES-256-GCM key, base64 of exactly 32 bytes ( |
| unset | Path of a file holding the key instead of |
| unset | Path of a file holding the database password (not together with |
| unset | Previous key, only during key rotation. Must differ from |
| unset | Issuer URL of the OIDC provider. Set all three |
| unset | Client ID registered for the gateway (with |
| unset | Client secret registered for the gateway (with |
|
| Members of this group may sign in. |
|
| Members of this group may sign in and are admins. |
|
| Scopes of the login request, space- or comma-separated; must include |
|
| Claim with the person's groups: a list of names, or an object whose keys are the names. |
|
| Catalog synchronisation period, hours (1-8760). |
|
| How long call log entries are kept. |
|
| Larger upstream responses are refused (memory protection). |
|
| Request body limit of |
|
|
|
| unset | Base URL of the embeddings API, only for |
| unset | Model name for |
|
| Directory of the local model. The image already contains it. |
|
| Cosine-similarity floor (0-1) for vector search candidates. |
|
|
|
OIDC setup
Optional: skip this section to run without a provider (see "First admin").
Any OIDC provider works if it can put the person's groups (or roles) into one claim of the ID token or the UserInfo response: a flat list of names, or an object whose keys are the names. The claim name is OIDC_GROUPS_CLAIM (default groups), the requested scopes are OIDC_SCOPES (default openid profile email groups).
Create two groups: the login group (
mcp-users) and the admin group (mcp-admins). Membership in either lets a person in; the admin group also makes them an admin.Create a confidential OIDC client:
redirect URI:
https://<host>/api/auth/callback;PKCE: allowed (the gateway always sends S256);
make sure the groups claim is emitted (see the table below).
Put the issuer, client ID and client secret into
OIDC_ISSUER,OIDC_CLIENT_ID,OIDC_CLIENT_SECRET, and setOIDC_SCOPES/OIDC_GROUPS_CLAIMif your provider needs it.
Provider | Settings |
Pocket ID, Authentik, Authelia, Kanidm | defaults |
Keycloak | defaults; add a client scope |
Zitadel |
|
Microsoft Entra ID |
|
Auth0 |
|
These are starting points, not tested recipes; check the claims your provider actually issues (for example on its token preview page) if login answers /?loginError=not_allowed.
Check the issuer with curl -s https://id.example.com/.well-known/openid-configuration. If login redirects to /?loginError=idp_unavailable, the gateway cannot reach OIDC_ISSUER; /mcp and existing tokens keep working.
Disabling a person in the UI revokes all their sessions and tokens.
Adding upstream servers
Upstreams must speak Streamable HTTP. Each server has a slug (kebab-case, the prefix of its tool refs, cannot be changed later), a URL, an auth mode, access (everyone or a list of groups), a call timeout and an optional daily limit per person.
Auth mode | Credentials |
| No header is sent. |
| One secret for the server, set by an admin, sent by the gateway for everyone. |
| Each person stores their own personal access token in Connections. |
| Each person connects their account via OAuth 2.0 (Authorization Code + PKCE); tokens are refreshed automatically. |
For all modes except none you set a header name and a template containing {secret}, e.g. Authorization / Bearer {secret}. Secrets in the form are write-only.
Order matters: add the server, then connect your own account in Connections, then press Sync. For oauth_user and pat_user servers the first sync right after creation reports that an admin connection is needed; that is expected. Scheduled syncs use the connection of the last admin who synced the server successfully; if that person loses the admin role, another admin with a connection must press Sync once.
Gitea (oauth_user)
Run
gitea-mcpin HTTP mode, with no global token (each request carries the person's token), reachable from the gateway and not published:gitea-mcp: image: docker.gitea.com/gitea-mcp-server command: ['/app/gitea-mcp', '-t', 'http', '--port', '8080', '-H', 'https://gitea.example.com']In Gitea: Site Administration -> Applications -> OAuth2 Applications -> create an app, Confidential Client on, redirect URI
https://<host>/api/connections/callback. Save the client ID and secret.Add the server in the gateway:
Field
Value
URL
http://gitea-mcp:8080/mcpAuth mode
oauth_userAuthorize URL
https://gitea.example.com/login/oauth/authorizeToken URL
https://gitea.example.com/login/oauth/access_tokenRevoke URL
empty (Gitea has no RFC 7009 endpoint)
Client ID, secret
from step 2
Scopes
empty (Gitea then grants the user's full access)
Header / template
Authorization/Bearer {secret}
A request with an invalid token to gitea-mcp returns HTTP 401; a connection error instead means the containers are not on the same network.
YouTrack (oauth_user)
YouTrack has a built-in MCP endpoint at /mcp. OAuth goes through Hub (built into YouTrack at <youtrack>/hub, or standalone).
Hub -> Services -> New service: redirect URI
https://<host>/api/connections/callback, set a secret. The service ID is the client ID.Note the ID of the YouTrack service in Hub: it is the scope.
Add the server:
Field
Value
URL
https://youtrack.example.com/mcpAuth mode
oauth_userAuthorize URL
<hub>/api/rest/oauth2/authToken URL
<hub>/api/rest/oauth2/tokenClient ID, secret
from step 1
Scopes
the YouTrack service ID from step 2
Extra authorize parameters
access_type=offline(required: without it Hub issues no refresh token and the connection expires after an hour)Header / template
Authorization/Bearer {secret}
A server with a shared key (shared_secret)
For an MCP server protected by one API key: auth mode shared_secret, header e.g. Authorization with template Bearer {secret} (or X-API-Key / {secret}), and the key as the server secret. Every permitted person calls it with the same key; the call log still records who called what.
Servers can also be created from a JSON file (ServerInput in packages/contracts/src/servers.ts); the secret is read from stdin or an environment variable, never from the command line:
docker compose exec -T app node dist/cli.js create-server --json /path/in/container/server.json \
--as <admin-sub> --secret-env UPSTREAM_KEYOperations
CLI
Inside the container: node dist/cli.js <command> (same environment as the server). Exit codes: 0 success, 1 operation failed, 2 bad invocation.
Command | Purpose |
| Create or update a person as a first login would. Idempotent by |
| Issue an |
| Print a one-time sign-in link (15 minutes) for an existing, enabled person. For servers without OIDC, or emergency access. |
| Create a server and sync it. The secret comes from |
| Sync a server's tools (without |
| Rebuild the search index (if |
| Re-encrypt every stored secret from |
| Remove the stored key check so the next start records the configured |
| Print the gateway version (needs no configuration and no database). |
Rotating SECRETS_KEY
Generate a new key and keep the old one until rotation is done.
Set
SECRETS_KEY_OLD=<current key>,SECRETS_KEY=<new key>, restart. Both keys open secrets meanwhile, so calls keep working; a warning is logged on each start.Run
node dist/cli.js rotate-secrets-key. It reports how many server secrets and connections were re-sealed and akey check:line (re-sealed,already current,none storedorcannot be read with either key). Exit code 1 lists records that neither key opens (wrong old key?).Run it again: it should report
0 re-sealedandkey check: already current. RemoveSECRETS_KEY_OLDand restart.
Quick start variant. The key lives in the secrets volume (SECRETS_KEY_FILE), so the new key is written there and the old one is passed as SECRETS_KEY_OLD. Run from the directory with the saved quickstart.compose.yml; add --env-file my.env to every docker compose -f ... command if you use one. Every command below was run against a quick-start stack:
OLD=$(docker compose -p mcp-registry exec -T app cat /secrets/secrets_key) # keep this value until the end
NEW=$(openssl rand -base64 32)
docker compose -p mcp-registry down # not "down -v"
printf '%s\n' "$NEW" | docker run --rm -i -v mcp-registry_secrets:/secrets \
--entrypoint sh pgvector/pgvector:pg17 -c 'cat > /secrets/secrets_key'
SECRETS_KEY_OLD="$OLD" docker compose -f quickstart.compose.yml up -d
docker compose -p mcp-registry exec -T app node dist/cli.js rotate-secrets-key # run twice
docker compose -f quickstart.compose.yml up -d # without SECRETS_KEY_OLD: the app is recreatedA successful run prints server secrets: N re-sealed ..., connections: ... and key check: re-sealed (then already current on the repeat). If the new key was not written correctly the app refuses to start; see below.
Back up SECRETS_KEY together with the database: a database restored without its key has no usable secrets or connections.
Key check and secrets from files
At every start the server compares SECRETS_KEY with a check value kept in the database. The check proves that the key is the one that was recorded on the first start with the check; it does not test the stored secrets themselves. On the first start, and the first start after upgrading from 0.1.0, the value is created from whatever key is configured at that moment. If the key opens it, the server continues. If only SECRETS_KEY_OLD opens it, the server continues and logs a warning to run rotate-secrets-key. If neither opens it, the server logs one fatal record and exits with code 1. The server never generates or replaces the key itself.
SECRETS_KEY_FILE and PGPASSWORD_FILE read the key and the database password from files (for example Docker secrets); surrounding whitespace is trimmed. Set either the variable or its _FILE twin, not both: that is a startup error, as is an unreadable or empty file. Errors name the variable (SECRETS_KEY_FILE for a bad key read from a file) and the path, never the content.
CLI commands warn on stderr when the stored check does not match the configured key; create-server, which would seal a new secret with the wrong key, is refused (exit 1). rotate-secrets-key and reset-key-check run regardless.
Recovering from a key mismatch
The app logs SECRETS_KEY does not match the data in this database; ... and restarts in a loop. First find out which case you are in.
1. The server pinned a wrong key on the first start after an upgrade. The check value is created from whatever key is configured on the first start with the check; it does not test existing secrets. If that key was wrong, the right key now looks like a mismatch. Put the right key back (SECRETS_KEY in .env, or the secrets_key file), remove the check, start:
docker compose run --rm app node dist/cli.js reset-key-check --yes # docker-compose.yml + .env
docker compose up -dFor the quick start, the key is the secrets_key file in the secrets volume. Stop the stack, write the right key into the file (the same command as in the rotation section, with $KEY holding the right key), remove the check and start:
docker compose -p mcp-registry down # not "down -v"
printf '%s\n' "$KEY" | docker run --rm -i -v mcp-registry_secrets:/secrets \
--entrypoint sh pgvector/pgvector:pg17 -c 'cat > /secrets/secrets_key'
docker compose -p mcp-registry -f quickstart.compose.yml run --rm app node dist/cli.js reset-key-check --yes
docker compose -p mcp-registry -f quickstart.compose.yml up -dRun the -f quickstart.compose.yml commands (here and in case 3) with the same --env-file and environment (including MCP_REGISTRY_IMAGE, if you set it) as when you started the stack; otherwise Compose recreates the stack with default settings.
When the app is in a restart loop docker compose exec fails ("container is restarting"); run --rm starts a separate one-off container with the same configuration and does not need the app to be up (the database starts if it is not running). The command prints key check removed: the next start records the configured SECRETS_KEY; the running app picks the new check up on its next restart attempt.
2. The key is lost for good. Server secrets and personal connections cannot be recovered. Put a new key in place (openssl rand -base64 32) and run the same reset-key-check --yes. People, tokens, the catalog and the call log remain; every server secret (UI: server, secret) and every person's connection must be entered again. Servers sealed under the lost key fail with an internal error until then.
3. Quick start: the secrets volume was lost, pgdata kept. init generates a new key and a new database password; Postgres still has the old password, so the app cannot connect. Set the database password to the new one, then continue as in case 2:
docker compose -p mcp-registry exec -T db sh -c \
'printf "alter user mcp password '\''%s'\'';\n" "$(cat /secrets/pg_password)" | psql -U mcp -d mcp'
docker compose -p mcp-registry -f quickstart.compose.yml run --rm app node dist/cli.js reset-key-check --yesalter user prints ALTER ROLE; the app then connects, and the second command ends the key mismatch loop. Do not use down -v: it deletes the data too.
Things to know
OAuth providers must be on HTTPS and on the same registrable domain as the gateway (e.g.
git.example.comandmcp.example.com). The session cookie isSameSite=Strict, so the browser does not send it on the redirect back from a provider on another site, and the connection fails witherror=unauthenticated.A wrong OAuth client secret does not break people's connections, but once their access tokens expire every call to that server fails as "unavailable" (
transport_errorin the call log) until the secret is fixed. Nobody has to reconnect. When rotating a client secret, update it in the gateway first, then revoke the old one at the provider.Search threshold.
SEARCH_MIN_SIMILARITY(default0.83, calibrated for the bundled model) is the floor for vector matches. Lower it (e.g.0.80) if the agent misses obvious tools, raise it if it finds unrelated ones. A restart is enough; no reindex. Recalibrate if you switch to another embedding model.Large tool outputs. Claude Code truncates MCP tool output at about 25k tokens (
MAX_MCP_OUTPUT_TOKENS); raise it on the client (MAX_MCP_OUTPUT_TOKENS=100000 claude) for large results. The gateway's 20 MiBUPSTREAM_MAX_RESPONSE_BYTESonly protects server memory.Scope. Streamable HTTP upstreams only (no stdio, no legacy SSE). Tools only: MCP resources and prompts are not proxied.
Call arguments and results are never logged. Daily limits reset at midnight UTC.
Versioning and upgrades
Releases follow semantic versioning; changes are listed in CHANGELOG.md. The version is shown by node dist/cli.js --version, under your name in the web UI sidebar, in the serverInfo that /mcp reports to MCP clients, and in the version field of the starting and listening log records.
What stays stable within 1.x
Environment variables: names and meaning. New ones may be added. The defaults of tuning values (
SEARCH_MIN_SIMILARITY,SYNC_INTERVAL_HOURS,CALL_LOG_RETENTION_DAYS,UPSTREAM_MAX_RESPONSE_BYTES,MCP_MAX_BODY_BYTES) may change in a minor release, with a changelog entry. Embeddings stay 384-dimensional for all of 1.x.CLI: command names, arguments and exit codes (0 success, 1 operation failed, 2 bad invocation). Output text is for people and may change, except that
create-tokenprints the token on the first line of stdout (the second line is theclaude mcp addcommand, the reminder goes to stderr) andlogin-linkprints the link as the only line on stdout./mcp: Streamable HTTP at/mcpwithAuthorization: Bearer sk_...; the four toolslist_servers,search_tools,describe_tool,call_tool; their input and output fields are not removed or changed in meaning (new optional fields may appear); the<server>.<tool>ref format.URLs registered outside the gateway:
<PUBLIC_URL>/api/auth/callbackand<PUBLIC_URL>/api/connections/callback;/healthzanswers 200 with the bodyok.Data: a database from 0.1.0 or from any earlier 1.x is upgraded automatically at startup; existing
sk_tokens, sessions and connections keep working across upgrades. The tables themselves are internal: do not read or write them.Deployment names that the documented commands rely on: in
quickstart.compose.ymlthe project namemcp-registry, the servicesapp,db,initand the volumessecretsandpgdata; in the image, port 3000 andnode dist/cli.js.
Not covered: the rest of /api/** (the web client's internal interface), and the shape and text of log records. Agents use /mcp, scripts use the CLI; for automation use login-link, not log parsing (the grep "one-time link" above is a convenience for a person).
Image tags
ghcr.io/ai-pipes/mcp-registry is published for tagged releases only, and only after the release workflow has tested the image. 1.0.0 is exactly that release; 1.0 and 1 point to the latest release of their line and latest to the latest release overall. The workflow sets them from the tag that was pushed last, not from the highest version, so releasing an older patch after a newer one moves them back. quickstart.compose.yml uses :1. To control when you upgrade, pin an exact tag: MCP_REGISTRY_IMAGE=ghcr.io/ai-pipes/mcp-registry:1.0.0.
Upgrading
There are no down migrations, so a backup is the way back. In the commands below, docker compose is the one you already use for the stack (the quick start needs -p mcp-registry, plus the same --env-file or environment as before).
Back up the database and the key. Source layout (
docker-compose.yml+.env):docker compose exec -T db pg_dump -Fc -U mcp -d mcp > mcp-$(date +%F).dump cp .env .env.backup # holds SECRETS_KEYQuick start (the key is the
secrets_keyfile in thesecretsvolume):docker compose -p mcp-registry exec -T db pg_dump -Fc -U mcp -d mcp > mcp-$(date +%F).dump (umask 077; docker compose -p mcp-registry exec -T app cat /secrets/secrets_key > secrets_key.backup)Keep the dump and the key together: a database restored without its key has no usable secrets.
Upgrade. Source layout: check out the release tag and rebuild.
git fetch --tags && git checkout v<version> docker compose up -d --buildQuick start: replace your saved
quickstart.compose.ymlwith the one from the release tag, then pull and start with the same--env-fileor environment as before. The--env-file my.envflag in the commands below is needed only if you started the stack with a settings file; without one, run the same commands without it.up -dalone does not pull a tag such as:1that is already cached;pullfetches the new image andup -dthen recreates the app.docker compose -p mcp-registry --env-file my.env -f quickstart.compose.yml pull docker compose -p mcp-registry --env-file my.env -f quickstart.compose.yml up -dStart with the key you have been using. The first start with a version that has the key check records it; a different key later stops the server (see "Recovering from a key mismatch"). Migrations run at startup under a lock; check
docker compose logs appfor thestartingrecord with the new version and forlistening.
Going back
A database that a newer version has migrated is refused by an older one, from 1.0.0 on (0.1.0 has no such check and starts on a database migrated by 1.x, so do not run it there without restoring): the server logs the database was migrated by a newer version of mcp-registry (unknown migration: ...) and exits with code 1 (Compose keeps restarting it; the CLI fails the same way). Going back means restoring the dump taken before the upgrade, which discards everything written since. Stop the app, recreate the database, restore, start the old version (use the docker compose of your layout as above):
docker compose stop app
docker compose exec -T db psql -U mcp -d postgres -c 'drop database mcp with (force)' -c 'create database mcp owner mcp'
docker compose exec -T db pg_restore -U mcp -d mcp --exit-on-error < mcp-2026-11-17.dumpThen start the old version: source layout, check out the old tag and docker compose up -d --build; quick start, MCP_REGISTRY_IMAGE=ghcr.io/ai-pipes/mcp-registry:<old version> docker compose -p mcp-registry --env-file my.env -f quickstart.compose.yml up -d with the old release's compose file (drop --env-file my.env if you do not use a settings file). Put the key from the backup back if you rotated it after the dump was taken.
Development
Requires Node 22, pnpm (version pinned in package.json) and Docker (integration tests start Postgres with Testcontainers).
pnpm install
pnpm verify # lint, format, types, architecture rules, knip, unit + integration tests, UI build
bash scripts/smoke.sh # end-to-end check of the built image: CLI -> MCP search -> describe -> call
bash scripts/e2e-image.sh # Playwright against the built image (pnpm exec playwright install chromium)
pnpm dev:web # UI dev server, proxies /api and /mcp to localhost:3000Architecture, layer rules and conventions: CONTRIBUTING.md and CLAUDE.md. Security reports: SECURITY.md.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
One MCP endpoint for your company's tools, with per-person sign-in, policy and audit.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI harnesses to connect to a single MCP endpoint that routes to multiple downstream MCP servers, discovering and executing capabilities on demand while keeping tool schemas out of context.441 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceProvides a unified MCP gateway enabling AI agents to securely access multiple tool servers (knowledge base, database, repo, etc.) with dynamic tool selection and OAuth2/RBAC security.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to connect through a single multiplexed SSE/HTTP endpoint to multiple local and remote MCP servers, with token authentication, per-tool approval policies, tool namespacing, and live telemetry.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLM agents to access multiple stdio or Streamable HTTP MCP servers through one authenticated endpoint, enforcing OAuth bearer validation, per-client tool RBAC, rate limits, schema validation, audit logging, and tool-definition pinning.MIT