[TESTING][FUNCTIONALITY]: Federation manual test plan (peer discovery, cross-gateway calls, sync) #2430
Description
🌍 [TESTING][FUNCTIONALITY]: Federation Manual Test Plan
Goal
Produce a comprehensive manual test plan for federation functionality including peer discovery, cross-gateway tool calls, synchronization, and trust management.
Why Now?
Federation enables distributed MCP infrastructure:
- Scalability: Distribute load across gateways
- Discovery: Find tools across federated peers
- Reliability: Failover to peer gateways
- Collaboration: Share resources between teams
📖 User Stories
US-1: Admin - Peer Management
As an administrator
I want to manage federated peers
So that gateways can share resources
Acceptance Criteria:
Feature: Peer Management
Scenario: Add peer gateway
Given another gateway is running
When I add it as a federated peer
Then it should appear in peer list
And its tools should be discoverable
Scenario: Remove peer gateway
Given a federated peer exists
When I remove the peer
Then its tools should no longer appearUS-2: Client - Cross-Gateway Access
As an MCP client
I want to access tools from federated gateways
So that I have unified access to all resources
Acceptance Criteria:
Feature: Cross-Gateway Access
Scenario: Discover federated tools
Given federated peers are configured
When I list tools with federation enabled
Then I should see tools from all peers
Scenario: Invoke federated tool
Given a tool exists on a peer gateway
When I invoke the tool
Then the request should be routed to the peer
And the result should be returned🏗 Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ FEDERATION ARCHITECTURE │
└─────────────────────────────────────────────────────────────────────────────┘
Gateway A Redis Gateway B
───────── ───── ─────────
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Gateway A │ │ Redis │ │ Gateway B │
│ (Primary) │◀─────▶│ Pub/Sub │◀─────▶│ (Peer) │
│ │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Tools A1-A5 │ │ Tools B1-B3 │
└──────────────┘ └──────────────┘
FEDERATED TOOL LIST
────────────────────
Client ──▶ Gateway A ──▶ [A1, A2, A3, A4, A5, B1@peer, B2@peer, B3@peer]
📋 Test Environment Setup
export GATEWAY_A_URL="http://localhost:8000"
export GATEWAY_B_URL="http://localhost:8001"
export REDIS_URL="redis://localhost:6379"
export TOKEN=$(python -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --secret "$JWT_SECRET")
# Start Gateway A
PORT=8000 make dev &
# Start Gateway B
PORT=8001 make dev &🧪 Manual Test Cases
Section 1: Peer Management
| Case | Scenario | Action | Expected | Validation |
|---|---|---|---|---|
| PM-01 | Add peer | POST | Peer added | In peer list |
| PM-02 | List peers | GET | Peers shown | Status visible |
| PM-03 | Remove peer | DELETE | Peer removed | Not in list |
| PM-04 | Peer health | GET | Status check | Online/offline |
PM-01: Add Federated Peer
Steps:
# Step 1: Add Gateway B as peer to Gateway A
curl -s -X POST "$GATEWAY_A_URL/api/federation/peers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"url\": \"$GATEWAY_B_URL\",
\"name\": \"gateway-b\",
\"trust_level\": \"full\"
}" | jq .
# Step 2: Verify peer is listed
curl -s "$GATEWAY_A_URL/api/federation/peers" \
-H "Authorization: Bearer $TOKEN" | jq '.[] | {name, url, status}'Expected Result:
- Peer added successfully
- Peer visible in list with status
Section 2: Tool Discovery
| Case | Scenario | Flag | Expected | Validation |
|---|---|---|---|---|
| TD-01 | Local only | false | Local tools | No peer tools |
| TD-02 | Federated | true | All tools | Peer tools included |
| TD-03 | Peer offline | true | Local + warning | Degraded federation |
TD-02: Discover Federated Tools
Steps:
# Step 1: List tools with federation
curl -s -X POST "$GATEWAY_A_URL/mcp/http" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {"include_federated": true}
}' | jq '.result.tools[] | {name, source}'
# Step 2: Verify tools from both gateways
SOURCES=$(curl -s -X POST "$GATEWAY_A_URL/mcp/http" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"include_federated": true}}' \
| jq -r '.result.tools[].source' | sort -u)
echo "$SOURCES"Expected Result:
- Tools from Gateway A and B listed
- Source indicates origin gateway
Section 3: Cross-Gateway Calls
| Case | Scenario | Tool | Expected | Validation |
|---|---|---|---|---|
| CG-01 | Invoke remote | Peer tool | Routed | Result returned |
| CG-02 | Peer timeout | Slow peer | Timeout | Error returned |
| CG-03 | Peer offline | Dead peer | Error | Clear message |
CG-01: Invoke Federated Tool
Steps:
# Step 1: Get a tool from peer gateway
PEER_TOOL=$(curl -s -X POST "$GATEWAY_A_URL/mcp/http" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"include_federated": true}}' \
| jq -r '.result.tools[] | select(.source == "gateway-b") | .name' | head -1)
# Step 2: Invoke the tool
curl -s -X POST "$GATEWAY_A_URL/mcp/http" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"jsonrpc\": \"2.0\",
\"id\": 1,
\"method\": \"tools/call\",
\"params\": {\"name\": \"$PEER_TOOL\", \"arguments\": {}}
}" | jq .Expected Result:
- Request routed to Gateway B
- Result returned through Gateway A
📊 Test Matrix
| Test Case | Peers | Discovery | Routing | Sync |
|---|---|---|---|---|
| PM-01 | ✓ | |||
| PM-02 | ✓ | |||
| PM-03 | ✓ | |||
| PM-04 | ✓ | |||
| TD-01 | ✓ | |||
| TD-02 | ✓ | |||
| TD-03 | ✓ | |||
| CG-01 | ✓ | |||
| CG-02 | ✓ | |||
| CG-03 | ✓ |
✅ Success Criteria
- All 10 test cases pass
- Peer management works
- Federated tool discovery works
- Cross-gateway invocation works
- Offline peer handling is graceful
🔗 Related Files
mcpgateway/services/federation_service.pymcpgateway/routers/federation.py