Skip to content

πŸš€ 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

BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

Local install via PyPI

Note

Prereqs: Python β‰₯ 3.11, plus curl & jq for the smoke test.

  1. Create an isolated environment and upgrade pip if required

    mkdir mcpgateway && cd mcpgateway
    python3 -m venv .venv && source .venv/bin/activate
    python3 -m pip install --upgrade pip
    
  2. Install the gateway from pypi

    pip install mcp-contextforge-gateway
    mcpgateway --version
    
  3. 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.

  4. 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

  5. Smoke-test health + version

    curl -s http://localhost:4444/health | jq
    curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/version | jq
    

Docker/Podman Container install

Note

Substitute docker with podman if preferred.

  1. Run the image

    docker run -d --name mcpgateway \
      -p 4444:4444 \
      -e HOST=0.0.0.0 \
      -e JWT_SECRET_KEY=my-test-key \
      -e BASIC_AUTH_USER=admin \
      -e BASIC_AUTH_PASSWORD=changeme \
      ghcr.io/ibm/mcp-context-forge:0.6.0
    
  2. (Optional) persist the DB

    mkdir -p $(pwd)/data
    docker run -d --name mcpgateway \
      -p 4444:4444 \
      -v $(pwd)/data:/data \
      -e DATABASE_URL=sqlite:////data/mcp.db \
      -e JWT_SECRET_KEY=my-test-key \
      -e BASIC_AUTH_USER=admin \
      -e BASIC_AUTH_PASSWORD=changeme \
      ghcr.io/ibm/mcp-context-forge:0.6.0
    
  3. Generate a token inside the container

    docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token \
      --username admin --exp 10080 --secret my-test-key
    
  4. Smoke-test

    export MCPGATEWAY_BEARER_TOKEN=<paste_from_previous_step>
    curl -s http://localhost:4444/health | jq
    curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/version | jq
    

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.

  1. Install Compose v2 (if needed)

    # Ubuntu example
    sudo apt install docker-buildx docker-compose-v2
    # Tell the Makefile / docs which command to use
    export COMPOSE_CMD="docker compose"
    
  2. Pull the published image

    docker pull ghcr.io/ibm/mcp-context-forge:0.6.0
    
  3. Start the stack

    # Uses podman or docker automatically
    make compose-up
    # -or- raw CLI
    docker compose -f docker-compose.yml up -d
    
  4. Verify

    curl -s http://localhost:4444/health | jq
    

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

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!