Skip to content

Onboarding New Servers

Learn how to create a wags proxy server that wraps existing MCP servers with middleware.

Prerequisites

Creating a wags Proxy Server

wags provides the quickstart command to generate proxy servers that wrap existing MCP servers with middleware.

Complete Example Available

The complete implementation for the GitHub MCP Server is in servers/github/.

Step 1: Prepare Your MCP Server Configuration

Create a configuration file that describes your MCP server. Save it as config.json:

config.json
{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server",
        "stdio"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Step 2: Generate the Proxy Server

Use the quickstart command to generate middleware handlers and main file:

Bash
# Generate both handlers and main files
wags quickstart config.json

# Or with custom file names
wags quickstart config.json \
  --handlers-file github_handlers.py \
  --main-file github_proxy.py

Step 3: Add Middleware Decorators

Edit the generated handlers file to add middleware decorators:

handlers.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from typing import Annotated

from wags.middleware import RequiresElicitation, requires_root


class GitHubHandlers:
    async def search_repositories(self, query: str, limit: int = 10):
        # Search method is safe: nothing to be done
        pass

    # Ensure that client has enabled access to this repository
    @requires_root("https://github.com/{owner}/{repo}")
    async def get_repository(self, owner: str, repo: str):
        pass

    @requires_root("https://github.com/{owner}/{repo}")
    async def create_issue(
        self,
        owner: str,
        repo: str,
        # Allow user to review and edit these fields
        # before actually invoking the tool
        title: Annotated[str, RequiresElicitation("Title")],
        body: Annotated[str, RequiresElicitation("Body")],
    ):
        pass

Step 4: Attach Middleware to your MCP Server

The automatically generated main.py includes (commented) code to attach wags middleware to your MCP server. You should edit the file to uncomment the middleware you need:

main.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from pathlib import Path

from handlers import GitHubHandlers

from wags import create_proxy, load_config
from wags.middleware import ElicitationMiddleware, RootsMiddleware

# Load configuration and create a proxy server
config = load_config(Path(__file__).parent / "config.json")
mcp = create_proxy(config, server_name="github-proxy")

# Handlers configure the middleware on what to do
handlers = GitHubHandlers()

# Add the configured middleware to your proxy server
mcp.add_middleware(RootsMiddleware(handlers=handlers))
mcp.add_middleware(ElicitationMiddleware(handlers=handlers))

if __name__ == "__main__":
    import asyncio

    asyncio.run(mcp.run_stdio_async())

Step 5: Run Your Proxy Server

Bash
# Run directly
python main.py

# Or use wags start-server
wags start-server servers/your-server

Your proxy server is now running!

Step 6 (Optional): Add to Shared Configuration

To use your server with wags run, add it to servers/fastagent.config.yaml:

YAML
mcp:
  servers:
    your-server:
      transport: stdio
      command: wags
      args:
        - start-server
        - servers/your-server
      env:
        API_KEY: ${YOUR_API_KEY}
      roots:
        - uri: https://example.com/allowed
          name: "Allowed Resources"

Now you can connect to your server with:

Bash
wags run --servers your-server

Learn More