WhereMyMCP

A self-hosted MCP gateway for your tools, accounts and agent clients.

Connect remote MCP servers, approve trusted servers in bulk, and choose what each agent can use. WhereMyMCP keeps provider credentials on your instance and issues separate, revocable tokens for your clients. One owner manages access through the dashboard.

Development release. Review the current limitations before deployment.

Dashboard preview from an isolated test instance.

Quick start · Connect an agent · Documentation · Development

Features

Bulk approval uses explicit destructiveHint: true for Delete, readOnlyHint: true for Read, and Write when hints are missing or unclear. Server metadata is trusted only after owner confirmation. Write/delete calls still require one-use approval; future metadata changes still quarantine tools. Bulk approval does not create profile grants.

New profiles grant no access by default. The owner signs in with a dashboard session; agents use profile-bound bearer tokens. Upstream requests use the credentials bound to the approved tool, rather than the agent's gateway token.

Related MCP server: ToolFunnel

How it works

flowchart LR
    Agents[Agent clients] -->|Client token| Gateway[WhereMyMCP /mcp]
    Owner[Owner dashboard] -->|Review, grants and approvals| Gateway
    Gateway --> Remote[Remote HTTP MCP servers]
    Gateway --> Providers[Native provider adapters]
    Gateway --- Store[SQLite state and encrypted credentials]

Quick start

1. Start the instance

Install Docker Engine with Docker Compose. From the repository root:

docker compose build init
docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:8080/health/ready

The init service builds the shared image and prepares persistent state and secret volumes. The hub service starts after initialization. Port 8080 binds to 127.0.0.1 by default.

2. Claim the owner account

Open http://127.0.0.1:8080. Read the one-time setup token in your terminal:

docker compose exec hub cat /secrets/bootstrap.token

Enter the token within 30 minutes and create the owner account. Passwords require at least eight characters, including lowercase, uppercase, a number and a symbol. Save the recovery codes when they appear; they are shown once.

Log in and enable authenticator MFA under Security. Owner claim closes bootstrap setup. For an expired setup token or a source installation, follow the installation guide.

3. Configure your first client

1. In Connections, add the credentials required by your server. An unauthenticated server can use no connection.

2. In MCP servers, register the remote endpoint and select its connection if needed.

3. In MCP servers, select the servers you trust and choose Auto approve selected servers. Confirm server trust. The batch refreshes discovery and enables current tools using their annotations. Manual Tool review remains available for individual overrides.

4. In Profiles & grants, open Default → Edit tool access. Select entire MCP servers or Select all available, then Save access. A new profile is optional.

5. In Agent clients, issue a token bound to that profile. Save it when it appears.

6. Generate the client configuration, set the token in the client's environment and connect to /mcp.

Write and delete calls also require approval through One-use approvals. Pass the returned approval ID as _meta.wheremymcp_approval_id on the tool call. See gateway compatibility for protocol details and limits.

Connect an agent

The default gateway endpoint is http://127.0.0.1:8080/mcp.

For Codex, add this to ~/.codex/config.toml:

[mcp_servers.wheremymcp]
url = "http://127.0.0.1:8080/mcp"
bearer_token_env_var = "WHEREMYMCP_TOKEN"

Set WHEREMYMCP_TOKEN in the environment used to launch the client, using the token shown at creation or rotation. Keep the credential out of committed configuration files.

The dashboard also generates configurations for Claude Code, Cursor and Gemini, plus transport guidance for Hermes and other clients. Installed client versions still need their own compatibility check; config generation alone does not prove interoperability. The compatibility report records the official SDK transports exercised locally.

Manage WhereMyMCP through MCP

Keep the same /mcp URL and client token used for provider tools. In Agent clients, choose Edit management access on the client you want to authorize, or select management access while issuing a client token. Management starts off. Choose Read for inspection, Read + Write for configuration changes, or Read + Write + Delete for full management. Confirm your owner password and authenticator code when MFA is enabled.

[mcp_servers.wheremymcp]
url = "http://127.0.0.1:8080/mcp"
bearer_token_env_var = "WHEREMYMCP_TOKEN"

Existing client configuration needs no new token, URL or second MCP entry when you enable management access. Reload the client's MCP connection to refresh its tools. Client config generates Codex, Claude, Cursor and Gemini formats, plus Hermes/other transport guidance. Provider tools remain controlled by the client's profile; built-in wheremymcp_manage_* tools follow its management permissions.

Example request: “Register this MCP server, approve its current tools, and give Default access to that server.” Management Write can issue ordinary agent tokens and change access; treat it as configuration administration. Only the owner can grant management access or rotate a management-enabled client token. Provider consent and owner security stay in the dashboard. Earlier separate /mcp/manage connections remain compatible. See Management MCP for scopes, tools and migration.

Connections and integrations

• Remote MCP endpoints can use bearer-token, API-key or remote OAuth connections.

• Native GitHub tools cover repositories, issues, file reads, issue creation and comments.

• Native Google tools cover Calendar and Drive operations within the configured app's granted scopes.

• Native Slack tools cover conversations, channel history and messages within the configured app's permissions.

OAuth integrations use your own provider app configuration. Consent, app verification, provider scopes and quotas still apply. See Connections and integrations. Live provider consent has not been verified by the local fixture tests.

Security and operations

Owner authentication uses Argon2id, optional TOTP MFA and one-use recovery codes. Browser mutations require CSRF protection. Stored client tokens are hashed; provider credentials and backups use authenticated encryption.

Every tool call checks current access policy, connection state, tool approval and metadata fingerprint. Audit events record decisions and timing without tool arguments, results or credentials. The gateway rejects redirects and blocks private and metadata destinations by default; intentional local connections require exact IP exceptions. No telemetry is sent.

Run one owner, one database and one application replica per instance. Retain the external master key separately from state and encrypted backups. Losing that key prevents credential and backup recovery. Follow the backup, restore and key rotation guide, including a restore into a fresh destination.

Public mode requires an exact HTTPS origin, explicitly trusted proxy IPs and owner MFA. Read the public deployment guide before exposing the service. Local tests do not replace an independent security review. Vulnerability reporting follows SECURITY.md.

Updating an initialized Docker instance

Check out the revision you intend to run and retain a backup plus the external master key. Then:

docker compose build init
docker compose up -d --no-deps --wait --wait-timeout 30 hub
curl --fail http://127.0.0.1:8080/health/ready

Both services use the image built by init. --no-deps replaces the application without rerunning initialization against an active database. Named volumes retain state and secrets.

docker compose down retains named volumes. Adding -v deletes them, including the database and master key.

Existing installations created under the former UnifyMCP name must retain their Compose project and volumes. See rename compatibility before changing deployment identifiers. Existing client tokens and encrypted backups remain supported.

Current limitations

• Single owner and single replica. There is no multi-tenant or hosted control plane.

• MCP tools use Streamable HTTP. Resources, prompts, legacy HTTP+SSE transport and resumable sessions are not implemented.

• Local stdio execution and shell hooks are disabled. Imported skill content is not executed.

• Skill publisher trust metadata and client-specific installation adapters are not implemented. Sync uses CLI preview and apply steps.

• The dashboard lists backups but does not track successful restore drills.

• Native client applications, live OAuth consent, physical mobile devices, screen readers and Kubernetes runtime need separate verification.

Documentation

Development

WhereMyMCP uses TypeScript, Fastify, SQLite WAL and a browser UI built with native JavaScript and CSS. Node.js 22.19.0+ and npm are required. Native SQLite and Argon2 dependencies may need a compiler toolchain when prebuilt binaries are unavailable.

npm ci
npx playwright install chromium
npm test
npm run typecheck
npm run build
npm run cli -- --help

On Linux, Chromium may also need system dependencies; CI uses npx playwright install --with-deps chromium. For running from source, configure the data directory and external master-key path using the installation guide.

src/            API, authentication, vault, providers and CLI
src/gateway/    MCP transport, discovery and call policy
public/         Owner dashboard
tests/          Unit, integration, browser and container checks
deploy/         Container initialization, proxy example and Helm chart
docs/           Installation, integrations and API guides

Tests cover browser workflows, SDK calls, backup/restore, migrations and OAuth failure paths. Live provider consent and installed-client compatibility require their own checks.

Follow CONTRIBUTING.md for changes. See CHANGELOG.md for repository history.

License

Licensed under the MIT License, copyright 2026 Rizki Darmawan. Package metadata retains private: true to prevent accidental npm publication. The setup instructions build from source and do not assume a published image or package.