MetaMCP

🔐Environment Variables & Secrets (STDIO MCP Servers)

ForSTDIO MCP servers, MetaMCP supports three ways to handle environment variables and secrets:

1. Raw Values- Direct string values (not recommended for secrets):

API_KEY=your-actual-api-key-here DEBUG=true

2. Environment Variable References- Use${ENV_VAR_NAME}syntax:

API_KEY=${OPENAI_API_KEY} DATABASE_URL=${DB_CONNECTION_STRING}

3. Auto-matching- If the expected environment variable name in your tool matches the container's environment variable, you can omit it entirely. MetaMCP will automatically pass through matching environment variables.

🔒 Security Note: Environment variable references (${VAR_NAME}) are resolved from the MetaMCP container's environment at runtime. This keeps actual secret values out of your configuration and git repository.

⚙️ Development Note: For local development withpnpm run dev:docker, ensure your environment variables are listed inturbo.jsonunderglobalEnvto be passed to the development processes. This is not required for production Docker deployments.

- Group one or more MCP servers into a namespace
- Enable/disable MCP servers or at tool level
- Apply middlewares to MCP requests and responses
- Override tool names/titles/descriptions per namespace and attach custom MCP annotations (e.g.{ "annotations": { "readOnlyHint": false } })

- Create endpoints and assign namespace to endpoints
- Multiple MCP servers in the namespace will be aggregated and emitted as a MetaMCP endpoint
- Choose between API-Key Auth (in header or query param) or standard OAuth in MCP Spec 2025-06-18
- Host throughSSEorStreamable HTTPtransports in MCP andOpenAPIendpoints for clients like[Open WebUI

- Intercepts and transforms MCP requests and responses at namespace level
- Built-in example: "Filter inactive tools" - optimizes tool context for LLMs
- Future ideas: tool logging, error traces, validation, scanning

Similar to the official MCP inspector, but withsaved server configs- MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.

- Open a namespace →Toolstab to see every tool coming from connected MCP servers.
- Each saved tool can be expanded and edited inline: update the displayname/title/descriptionor provide a JSON blob with namespace-specific annotations (for example{ "annotations": { "readOnlyHint": false } }).
- Badges in the table ("Overridden", "Annotations") show which tools currently have custom metadata. Hover them to read a tooltip describing what was overridden.
- Annotation overrides are merged with whatever the upstream MCP server returns, so you can safely add custom UI hints without losing provider metadata.

Clone repo, prepare.env, and start with docker compose:

git clone https://github.com/metatool-ai/metamcp.git cd metamcp cp example.env .env docker compose up -d

If you modify APP_URL env vars, make sure you only access from the APP_URL, because MetaMCP enforces CORS policy on the URL, so no other URL is accessible.

Note that the pg volume name may collide with your other pg dockers, which is global, consider rename it indocker-compose.yml:

volumes: metamcp_postgres_data: driver: local

📦 Build development environment with Dev Containers (VSCode/Cursor)

You can use the VSCode/Cursor extension to build the development environment in a container.

It only requires that you have an environment running Docker or a similar alternative (thedocker/docker composecommand is required), and no other dependent components need to be installed on your host machine.
- First, clone the MetaMCP source code, open project in Visual Studio Code.

git clone https://github.com/metatool-ai/metamcp.git cd metamcp code .

- Switch to Dev Containers. Open the VSCode Command Palette, and executeDev Containers: Reopen in Container.

VSCode will open the Dev Containers project in a new window, where it will build the runtime and install the toolchain according to theDockerfilebefore starting the connection and finally installing the MetaMCP dependencies.

noteThis process requires a reliable network connection, and it will access Docker Hub, GitHub, and some other sites. You will need to ensure the network connection yourself, otherwise the container build may fail.

Wait some minutes, depending on the internet connection or computer performance, it may take from a few minutes to tens of minutes, you can click on the Progress Bar in the bottom right corner to view a live log where you will be able to check unusual stuck.

After finished, you can runpnpm devto start the development server.

Still recommend running postgres through docker for easy setup:

- ✅Tools, Resources, and Promptssupported
- ✅OAuth-enabled MCP serverstested for 03-26 version

If you have questions, feel free to leaveGitHub issuesorPRs.

{ "mcpServers": { "MetaMCP": { "url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse" } } }