Agent Integration

This guide helps AI agents use the MCP Gateway effectively. The gateway provides unified access to multiple MCP servers through a single endpoint.

Quick Start

1. list_servers()              # What servers are available?
2. list_tools(server="x")      # What can this server do?
3. call(server="x", tool="y", args={...}, cwd="...") # Do it

Need help? Use docs(search="your question") at any time.

Gateway Tools Reference

Tool	Purpose	Example
list_servers()	List available servers	list_servers(cwd="/workspace")
list_all_servers()	List ALL configured servers	list_all_servers()
get_server_config(server)	Get server config details	get_server_config(server="github")
get_health()	Get health report for all servers	get_health()
list_tools(server)	List server's tools	list_tools(server="github")
describe_tool(server, tool)	Get tool schema	describe_tool(server="github", tool="create_issue")
call(server, tool, args, cwd)	Execute a tool	call(server="fs", tool="read_file", args={...}, cwd="...")
list_catalog()	Browse installable servers	list_catalog()
install_server(server, scope)	Install from catalog	install_server(server="sqlite", scope="global")
manage_config(action, ...)	Modify gateway config	manage_config(action="get")
docs(search)	Search documentation	docs(search="environment variables")

Common Use Cases

"I need to use a tool but don't know what's available"

# Step 1: See available servers
list_servers()

# Step 2: Pick a server, see its tools
list_tools(server="github")

# Step 3: Get details on a specific tool
describe_tool(server="github", tool="create_issue")

# Step 4: Call the tool with workspace context
call(
    server="github",
    tool="create_issue",
    args={"title": "Bug fix", "body": "..."},
    cwd="/path/to/workspace"
)

"I need to install a new MCP server"

# Browse the catalog
list_catalog()

# Install globally (available to all workspaces)
install_server(server="playwright", scope="global")

# Or install for a specific workspace
install_server(server="playwright", cwd="/path/to/workspace")

Important

• Global installs require scope="global" - this prevents accidental global modifications.
• If env vars are missing, inform the user to add them to their .env file - never pass credentials via parameters.

"I'm getting authentication/permission errors"

# Check if you're passing workspace context
call(server="github", tool="...", cwd="/path/to/workspace")  # cwd is required!

# Check what env vars the server needs
docs(search="github environment variables")

# Make sure .env file exists at workspace root with required vars

"I need to search documentation"

# Search for any topic
docs(search="how to configure postgres")

# Browse available topics
docs()

# Get help with errors
docs(search="MISSING_ENV_VARS error")

Workspace Context

Most operations need to know which workspace you're working in. This determines:

• Which .env file to load
• Which servers are available
• Which credentials to use

How to Pass Context

Option 1: In every request (recommended)

call(server="x", tool="y", args={...}, cwd="/path/to/workspace")

Option 2: Via HTTP headers (set once per session)

X-MCP-Workspace: /path/to/workspace
# Legacy alias:
X-MCP-Cwd: /path/to/workspace

Option 3: Via project token (remote access)

When using a project-specific bearer token, the project is automatically identified from the token. No need to pass cwd or headers.

Error Handling

The gateway provides helpful errors. Always check hint and suggestion fields.

Error Code	Meaning	What to Do
TOOL_NOT_FOUND	Tool doesn't exist on server	Run list_tools(server="...")
SERVER_UNAVAILABLE	Server crashed or won't start	Check logs, try install_server()
MISSING_ENV_VARS	Server needs API keys	Add to .env file in workspace root
ACCESS_DENIED	Wrong workspace context	Pass correct cwd parameter
SCOPE_REQUIRED	Global change without scope	Add scope="global" to request

Example Error Response

{
  "error": "Global install requires explicit scope",
  "hint": "To install globally, use: install_server(server=\"sqlite\", scope=\"global\")",
  "suggestion": "install_server(server=\"sqlite\", scope=\"global\")"
}

Self-Service Help

The docs() tool searches the gateway's knowledge base. Use it when stuck:

# General questions
docs(search="how do I configure a new server")

# Error help
docs(search="what does ACCESS_DENIED mean")

# Feature questions
docs(search="http headers workspace context")

# Server-specific help
docs(search="postgres setup")

Configuration Changes

All config modifications require explicit scope="global":

# Install a server globally
install_server(server="sqlite", scope="global")

# Add a new server to config
manage_config(
    action="add_server",
    name="my-custom-server",
    scope="global",
    data={"url": "http://localhost:9000/mcp"}
)

# Map a workspace path to profiles
manage_config(
    action="set_workspace",
    scope="global",
    cwd="/home/user/my-app",
    profiles=["github-work", "supabase-prod"]
)

# Read config (no scope needed)
manage_config(action="get")

# Validate config (no scope needed)
manage_config(action="validate")

# Export masked config (no scope needed)
manage_config(action="export")

Best Practices

1. Explore before guessing - Use list_tools and describe_tool instead of guessing tool names
2. Always pass context - Include cwd in tool calls for proper credential resolution
3. Read error hints - The gateway tells you exactly how to fix problems
4. Use docs() - Self-service help is built into the gateway
5. Be explicit with scope - Config changes need scope="global" to prevent accidents
6. Never pass secrets inline - If env vars are missing, inform the user to add them to .env - credentials are resolved automatically from the env resolution chain