π Quick Start¶
MCP Gateway can be running on your laptop or server in < 5 minutes. Pick an install method below, generate an auth token, then walk through a real tool + server demo.
Installing and starting MCP Gateway¶
Note
Prereqs: Install uv (https://docs.astral.sh/uv/getting-started/installation/)
Local install via PyPI¶
Note
Prereqs: Python β₯ 3.11, plus curl
& jq
for the smoke test.
-
Create an isolated environment and upgrade pip if required
-
Install the gateway from pypi
-
Launch it, listening on all interfaces
export BASIC_AUTH_PASSWORD=changeme export JWT_SECRET_KEY=my-test-key mcpgateway --host 0.0.0.0 --port 4444
The terminal shows startup logs; keep it running.
-
Generate a bearer token with an expiration time of 10080 seconds (1 week)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \ --username admin --exp 10080 --secret my-test-key)
Use
--exp 0
for tokens that don't expire -
Smoke-test health + version
Docker/Podman Container install¶
Note
Substitute docker
with podman
if preferred.
-
Run the image
-
(Optional) persist the DB
-
Generate a token inside the container
-
Smoke-test
Run the full stack with Compose¶
Typical Compose file includes Gateway + Postgres + Redis and optional PgAdmin / Redis Commander. See the complete sample and advanced scenarios in Deployment βΊ Compose.
-
Install Compose v2 (if needed)
-
Pull the published image
-
Start the stack
-
Verify
Tip : The sample Compose file has multiple database blocks (Postgres, MariaDB, MySQL, MongoDB) and admin tools. Uncomment one and align
DATABASE_URL
for your preferred backend.
Registering MCP tools & creating a virtual server¶
# Spin up a sample MCP time server (SSE, port 8002)
pip install uv
python3 -m mcpgateway.translate \
--stdio "uvx mcp_server_time -- --local-timezone=Europe/Dublin" \
--expose-sse \
--port 8002 &
# Register that server with your gateway
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"local_time","url":"http://localhost:8002/sse"}' \
http://localhost:4444/gateways | jq
# Bundle the imported tool(s) into a virtual MCP server
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"demo_server","description":"Time tools","associatedTools":["1"]}' \
http://localhost:4444/servers | jq
# Verify catalog entries
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers | jq
# Optional: Connect interactively via MCP Inspector
npx -y @modelcontextprotocol/inspector
# Transport SSE β URL http://localhost:4444/servers/UUID_OF_SERVER_1/sse
# Header Authorization β Bearer $MCPGATEWAY_BEARER_TOKEN
Connect via mcpgateway-wrapper
(stdio)¶
export MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN
export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp
python3 -m mcpgateway.wrapper # behaves as a local MCP stdio server - run from MCP client
Use this in GUI clients (Claude Desktop, Continue, etc.) that prefer stdio. Example:
{
"mcpServers": {
"mcpgateway-wrapper": {
"command": "python3",
"args": ["-m", "mcpgateway.wrapper"],
"env": {
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp",
"MCP_AUTH": "<YOUR_JWT_TOKEN>",
"MCP_TOOL_CALL_TIMEOUT": "120"
}
}
}
}
For more information see MCP Clients
4 - Useful URLs¶
URL | Description |
---|---|
http://localhost:4444/admin | Admin UI (Basic Auth: admin / changeme ) |
http://localhost:4444/tools | Tool registry (GET) |
http://localhost:4444/servers | Virtual servers (GET) |
/servers/<id>/sse | SSE endpoint for that server |
/docs , /redoc | Swagger / ReDoc (JWT-protected) |
5 - Next Steps¶
- Features Overview - deep dive on transports, federation, caching
- Admin UI Guide
- Deployment to K8s / AWS / GCP / Azure
- Wrap any client via
mcpgateway-wrapper
- Tweak
.env
- see example
Gateway is ready!
You now have an authenticated MCP Gateway proxying a live tool, exposed via SSE and stdio. Jump into the Admin UI or start wiring it into your agents and clients!