Prerequisites
Before starting, ensure you have:- Docker and Docker Compose installed
- Git for cloning the repository
- Basic understanding of MCP (Model Context Protocol)
Step 1: Installation
Clone the Repository
Clone the Repository
Clone MetaMCP from GitHub and navigate to the project directory:
Configure Environment
Configure Environment
Copy the example environment file and customize as needed:
If you modify
APP_URL in the .env file, make sure you only access MetaMCP from that URL due to CORS policy enforcement.In production environment, make sure you modify POSTGRES_PASSWORD and BETTER_AUTH_SECRET. Also use HTTPS. A typical way to generate secrets is
openssl rand -hex 32 | base64Start with Docker Compose
Start with Docker Compose
Launch MetaMCP using Docker Compose:This will start:
- MetaMCP fullstack docker image
- PostgreSQL database
The first startup may take a few minutes as Docker images are pulled and downloaded.
Step 2: Access MetaMCP
Once the containers are running:- Open your browser and go to
http://localhost:12008(or your configuredAPP_URL) - Create an account or log in
- Explore the dashboard - you’ll see sections for MCP Servers, Namespaces, and Endpoints
- (Optional) Disable signup You may only allow you and your team access MetaMCP, so once you setup the accounts, you can disable new user registration in Settings page.
Step 3: Configure Your First MCP Server
Step 3.1: Add a MCP Server
Step 3.1: Add a MCP Server
- Navigate to MCP Servers in the sidebar (or you can quickly add one from Explore & Search page)
- Click “Add Server” button (top right)
- In the dialog that opens, fill out the server configuration:
- Name:
hackernews-server(must be URL-compatible: letters, numbers, underscores, hyphens only) - Description:
HackerNews MCP server for fetching stories and comments - Type: Select
STDIOfrom dropdown
- Command:
uvx - Arguments:
mcp-hn(space-separated arguments) - Environment Variables: Leave empty (format:
KEY=value, one per line)
- Choose “For myself (Private)” or “Everyone (Public)”
- Private servers are only accessible to you
- Public servers are accessible to all users
- Click “Create Server”
- You should see a success message: “MCP Server Created”
After creating the server, you can click on it to view details, test the connection, and see available tools.
Step 3.2: Create a Namespace
Step 3.2: Create a Namespace
Why Namespaces? Namespaces group multiple MCP servers together and provide a unified endpoint for external access.
- Go to Namespaces in the sidebar
- Click “Create Namespace” button (top right)
- Fill out the namespace form:
- Name:
news-information(descriptive name for your server group) - Description:
Namespace containing news and information retrieval tools
- Choose “For myself (Private)” or “Everyone (Public)”
- You’ll see a list of available MCP servers with checkboxes
- Check the box next to your “hackernews-server”
- You can select multiple servers for one namespace
- Each server shows its type (STDIO, SSE, etc.) and description
- Click “Create Namespace”
- Success message: “Namespace Created”
You can add or remove servers from a namespace later by editing it.
Step 4: Manage Tools in Your Namespace
Review and Disable Unused Tools
Review and Disable Unused Tools
Why Manage Tools? Each MCP server may expose many tools, but you might only want to make certain tools available through your endpoint.
- Go to Namespaces in the sidebar
- Click on your “news-information” namespace to view details
- You’ll see three main sections:
- Check if the namespace can connect to its MCP servers
- Green status means all servers are reachable
- Click “Connect” if needed to establish connection
- View all servers assigned to this namespace
- See server status (Active/Inactive/Error)
- Monitor server health and configuration
- See all tools available from your servers
- Each tool shows:
- Tool name (e.g.,
get_top_stories,get_story) - Source server (which server provides this tool)
- Description and input schema
- Status (enabled/disabled)
- Tool name (e.g.,
- Disable unwanted tools:
- Uncheck tools you don’t want to expose via the endpoint
- For example, you might keep
get_top_storiesbut disableget_user_info - This helps keep your endpoint focused and secure
- Refresh Tools if needed to get latest tools from servers
Only enabled tools will be available when external applications use your endpoint.
Step 5: Create an Endpoint
Create Your Public Endpoint
Create Your Public Endpoint
What are Endpoints? Endpoints provide external access to your namespaces via HTTP APIs that other applications can consume.
- Navigate to Endpoints in the sidebar
- Click “Create Endpoint” button (top right)
- Configure your endpoint:
- Name:
news-endpoint(URL-compatible name - this becomes/metamcp/news-endpoint) - Description (Optional):
Public endpoint for news and information tools
- Choose “For myself (Private)” or “Everyone (Public)”
- Click the “Select a namespace” dropdown
- Choose your “news-information” namespace
- You’ll see the namespace name and description in the dropdown
- Enable API Key Authentication: Toggle ON (recommended)
- This requires API keys for endpoint access
- Use Query Parameter Authentication: Toggle ON/OFF
- When ON: Allows
?api_key=xxxin URLs - When OFF: Only accepts API keys in
Authorization: Bearer xxxheaders
- When ON: Allows
- “Automatically create an MCP server for this endpoint”: Check this box
- This creates a Streamable HTTP MCP server configuration for inspection
- Click “Create Endpoint”
- Success message: “Endpoint Created”
- SSE:
http://localhost:12008/metamcp/news-endpoint/sse - Streamable HTTP:
http://localhost:12008/metamcp/news-endpoint/mcp - OpenAPI:
http://localhost:12008/metamcp/news-endpoint/api - Schema:
http://localhost:12008/metamcp/news-endpoint/api/openapi.json
Step 6: Generate API Key
Create API Key
Create API Key
- Go to API Keys in the sidebar
- Click “Generate Key” button
- Fill out the API key form:
- Description:
My first MetaMCP API key for news endpoint - Scope:
- Private: Only you can use this key
- Public: All users can use this key
- Click “Generate Key”
- Important: Copy and save the key securely - it starts with
sk_mt_ - This key will be used to authenticate requests to your endpoints
The API key is only shown once. Make sure to copy it immediately.
Step 7: Managing Your Configuration
Managing MCP Servers
Managing MCP Servers
View Server Details:
- Click on any server in the MCP Servers list
- See connection status, available tools, and configuration
- Test server connection and inspect tools
- Use the actions menu (⋯) next to each server
- Modify configuration, add environment variables
- Update commands and arguments
- Active: Server is running and available
- Inactive: Server is configured but not running
- Error: Server has connection issues
Managing Namespaces
Managing Namespaces
View Namespace Details:
- Click on any namespace to see its servers and tools
- Monitor which servers are active in the namespace
- View aggregated tools from all servers
- Add or remove servers from existing namespaces
- Update name and description
- Change ownership settings
- See all tools available across servers in the namespace
- Enable/disable specific tools
- View tool schemas and documentation
Managing Endpoints
Managing Endpoints
Endpoint URLs:
Each endpoint provides multiple access methods:
- SSE: Server-Sent Events for real-time communication
- Streamable HTTP: HTTP-based MCP communication
- OpenAPI: REST API with OpenAPI documentation
- Schema: OpenAPI JSON schema for integration
- Use the actions menu (⋯) to copy specific URLs
- Copy URLs with or without embedded API keys
- Use different formats for different integrations
- Change which namespace an endpoint maps to
- Update authentication settings
- Modify access permissions
Next Steps
Add More Servers
Learn how to configure different types of MCP servers (STDIO, HTTP, etc.)
Configure Middleware
Apply middleware to filter tools and transform requests/responses
Connect to Cursor
Configure Cursor IDE to use your MetaMCP endpoints
Connect to Claude Desktop
Set up Claude Desktop with MetaMCP using mcp-proxy
Troubleshooting
Common Issues
Common Issues
CORS errors: Ensure you’re accessing MetaMCP from the URL specified in
APP_URL.Database connection: Check that PostgreSQL container is running with docker ps.Memory issues: MetaMCP requires at least 2GB RAM for optimal performance.Server connection failures: Check MCP server logs in the server detail pages.Authentication issues: Verify API keys are active and correctly formatted.Need Help?
Need Help?
- Browse GitHub Issues
- Join our Discord community