mcphub/docs/MULTI_ENDPOINT_GUIDE.md

Multi-Endpoint Architecture Guide

Solving the Tool Visibility Problem

---

The Problem

Before (Single Endpoint)

Client connects to /mcp
    ↓
Sees ALL 188 tools
    ↓
API key for site4 can see:
  - ✅ WordPress tools (but for all sites!)
  - ❌ Gitea tools (shouldn't see)
  - ❌ System tools (shouldn't see)
  - ❌ API key management (security risk!)

Issue

• Users saw tools they couldn't use
• Wasted AI context on irrelevant tools
• Security concern: tool enumeration
• Confusing UX

---

The Solution

After (Multi-Endpoint)

Client connects to /mcp/wordpress
    ↓
Sees ONLY 92 WordPress tools
    ↓
Clean, focused, secure

---

Endpoint Overview

Endpoint	Tools	Requires	Use Case
/mcp	188	Master Key	Admin operations
/mcp/wordpress	92	API Key	WordPress management
/mcp/wordpress-advanced	22	Admin Key	DB/Bulk/System ops
/mcp/gitea	55	API Key	Git management
/mcp/project/{id}	Varies	Project Key	Single project

---

Migration Guide

For Existing Users

Before (v1.x)

{
  "mcpServers": {
    "coolify": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer cmp_xxx"
      }
    }
  }
}

After (v2.0)

{
  "mcpServers": {
    "wordpress": {
      "url": "https://mcp.example.com/mcp/wordpress",
      "headers": {
        "Authorization": "Bearer cmp_xxx"
      }
    },
    "gitea": {
      "url": "https://mcp.example.com/mcp/gitea",
      "headers": {
        "Authorization": "Bearer cmp_yyy"
      }
    }
  }
}

Benefits After Migration

• Faster tool discovery
• Less AI context used
• Better security
• Clearer access control

---

API Key Configuration

Creating WordPress-Only Key

# Using admin endpoint with Master Key
curl -X POST https://mcp.example.com/mcp \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "manage_api_keys_create",
    "arguments": {
      "project_id": "wordpress_site1",
      "scope": "write",
      "name": "Site1 Editor"
    }
  }'

Key Scopes

Scope	Permissions
read	Read-only operations
write	Read + create/update
admin	Full access + system tools

---

Endpoint Details

/mcp - Admin Endpoint

Access: Master API Key (sk-*) only

Tools: All 188 tools including:

• WordPress Core (92)
• WordPress Advanced (22)
• Gitea (55)
• System tools (19)
• API key management
• OAuth management

Use Cases:

• Initial setup
• Creating API keys
• System monitoring
• OAuth client management

---

/mcp/wordpress - WordPress Endpoint

Access: Any valid API key

Tools: 92 WordPress tools

• Posts & Pages
• Media
• Taxonomy
• Comments
• Users
• WooCommerce
• SEO

Blacklisted Tools:

• manage_api_keys_*
• oauth_*
• System tools

Use Cases:

• Content management
• WooCommerce operations
• SEO management

---

/mcp/wordpress-advanced - Advanced WordPress Endpoint

Access: Admin scope required

Tools: 22 advanced tools

• Database operations
• Bulk operations
• System operations

Use Cases:

• Database backup/restore
• Bulk content updates
• System maintenance

---

/mcp/gitea - Gitea Endpoint

Access: Any valid API key (with gitea project)

Tools: 55 Gitea tools

• Repository management
• Issue tracking
• Pull requests
• Webhooks

Use Cases:

• Git operations
• Issue management
• PR reviews

---

/mcp/project/{id} - Project Endpoint

Access: API key matching project_id

Tools: Plugin tools filtered to single project

Example: /mcp/project/wordpress_site1

• Only WordPress tools
• Site parameter auto-set to site1

Use Cases:

• Single-site management
• Restricted access per client

---

Security Considerations

Tool Blacklisting

System and admin tools are blacklisted from non-admin endpoints:

tool_blacklist = {
    "manage_api_keys_create",
    "manage_api_keys_delete",
    "manage_api_keys_rotate",
    "oauth_register_client",
    "oauth_revoke_client",
}

API Key Validation

Each endpoint validates:

1. Token format and validity
2. Scope requirements
3. Plugin type matching
4. Tool-level access

Audit Logging

All tool calls are logged with:

• Endpoint path
• Tool name
• API key ID
• Timestamp
• Success/failure

---

Running the Server

Development

# Install dependencies
pip install -r requirements.txt

# Run multi-endpoint server
python server_multi.py --port 8000

Production (Docker)

# Build
docker-compose build

# Run
docker-compose up -d

Environment Variables

# Required
MASTER_API_KEY=sk-your-secure-key

# WordPress
WORDPRESS_SITE1_URL=https://example.com
WORDPRESS_SITE1_USERNAME=admin
WORDPRESS_SITE1_PASSWORD=app_password

# Gitea
GITEA_SITE1_URL=https://gitea.example.com
GITEA_SITE1_TOKEN=your-token

---

Testing Endpoints

Check Available Endpoints

curl http://localhost:8000/endpoints

Check Health

curl http://localhost:8000/health

Test WordPress Endpoint

curl -X POST http://localhost:8000/mcp/wordpress \
  -H "Authorization: Bearer cmp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tool": "wordpress_list_posts", "arguments": {"site": "site1"}}'

---

Troubleshooting

"Endpoint requires master API key"

• Use /mcp endpoint with Master Key for admin operations
• Or use appropriate plugin endpoint with project API key

"API key cannot access this endpoint"

• API key project_id must match endpoint plugin type
• Example: wordpress_site1 key works on /mcp/wordpress, not /mcp/gitea

"Access denied to tool"

• Tool may be blacklisted for this endpoint
• Check if admin scope is required

---

Future Improvements

• Per-project endpoints (/mcp/project/{id})
• Dynamic endpoint creation
• Custom tool whitelists
• Endpoint-level rate limiting
• Endpoint usage analytics

---

Last Updated: 2025-11-24