mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-07-09 14:04:19 +00:00
157 lines
3.3 KiB
Markdown
157 lines
3.3 KiB
Markdown
# MCP Gateway — Server Discovery and Catalog Sync
|
|
|
|
## Goal
|
|
|
|
This evolution allows the MCP Gateway to discover tools from registered MCP Servers by reading a manifest or catalog endpoint.
|
|
|
|
The framework still points to a single MCP Gateway:
|
|
|
|
```env
|
|
MCP_GATEWAY_ENABLED=true
|
|
MCP_GATEWAY_URL=http://localhost:8300
|
|
MCP_GATEWAY_TIMEOUT_SECONDS=60
|
|
```
|
|
|
|
The MCP Gateway can point to many MCP Servers:
|
|
|
|
```text
|
|
Agent Framework
|
|
-> MCP Gateway
|
|
-> telecom_mcp_server
|
|
-> retail_mcp_server
|
|
-> nf_items_mcp_server
|
|
-> any other MCP Server
|
|
```
|
|
|
|
## What is automatic
|
|
|
|
After a server is registered in `apps/mcp_gateway/config/mcp_gateway.yaml` with `discover: true`, the gateway can:
|
|
|
|
- call its manifest/catalog endpoint;
|
|
- normalize the returned tool list;
|
|
- publish the tools in `GET /v1/tools`;
|
|
- execute the discovered tool through `POST /v1/tools/{tool_name}/invoke`.
|
|
|
|
## What is still explicit
|
|
|
|
The gateway does not scan the network or GitHub by itself. You still register the MCP Server endpoint in YAML.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
servers:
|
|
nf_items:
|
|
enabled: true
|
|
discover: true
|
|
protocol: legacy_http
|
|
transport: http
|
|
url: http://localhost:8400/mcp
|
|
catalog_endpoint: /tools
|
|
invoke_endpoint: /tools/call
|
|
timeout_seconds: 30
|
|
```
|
|
|
|
If `catalog_endpoint` is omitted, the gateway tries:
|
|
|
|
```text
|
|
/.well-known/mcp-server.json
|
|
/manifest
|
|
/mcp/tools
|
|
/tools/list
|
|
/tools
|
|
/v1/tools
|
|
```
|
|
|
|
## Expected manifest/catalog formats
|
|
|
|
The gateway accepts common shapes:
|
|
|
|
```json
|
|
{
|
|
"server_id": "nf_items",
|
|
"tools": [
|
|
{
|
|
"name": "buscar_notas_por_criterios",
|
|
"description": "Search invoice items by criteria.",
|
|
"input_schema": {
|
|
"cliente": "string",
|
|
"estado": "string",
|
|
"preco": "number",
|
|
"ean": "string",
|
|
"margem": "number"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
It also accepts:
|
|
|
|
```json
|
|
{"tools": [...]}
|
|
```
|
|
|
|
```json
|
|
{"data": {"tools": [...]}}
|
|
```
|
|
|
|
```json
|
|
{"capabilities": {"tools": [...]}}
|
|
```
|
|
|
|
## New endpoints
|
|
|
|
### List discovery servers
|
|
|
|
```bash
|
|
curl http://localhost:8300/v1/discovery/servers | jq
|
|
```
|
|
|
|
### Force catalog sync
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8300/v1/discovery/sync | jq
|
|
```
|
|
|
|
### List merged static + discovered tools
|
|
|
|
```bash
|
|
curl http://localhost:8300/v1/tools | jq
|
|
```
|
|
|
|
## Precedence rule
|
|
|
|
Static tools configured under `tools:` override discovered tools with the same name. This allows operations teams to override timeout, cache, allowed agents, required business keys, and endpoint behavior safely.
|
|
|
|
## Plugging a new MCP Server
|
|
|
|
1. Start the MCP Server.
|
|
2. Confirm that it exposes a catalog or manifest endpoint.
|
|
3. Add it under `servers:` in `mcp_gateway.yaml` with `discover: true`.
|
|
4. Restart the MCP Gateway or call `POST /v1/discovery/sync`.
|
|
5. Confirm the tool appears in `GET /v1/tools`.
|
|
6. Invoke the tool through the gateway.
|
|
|
|
## Example invocation
|
|
|
|
```bash
|
|
curl -s -X POST http://localhost:8300/v1/tools/buscar_notas_por_criterios/invoke \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"tenant_id": "default",
|
|
"agent_id": "telecom_contas",
|
|
"channel": "web",
|
|
"tool_name": "buscar_notas_por_criterios",
|
|
"arguments": {
|
|
"cliente": "CLIENTE-001",
|
|
"estado": "SP",
|
|
"preco": 100.0,
|
|
"ean": "7890000000000",
|
|
"margem": 0.05
|
|
},
|
|
"business_context": {
|
|
"session_key": "session-001"
|
|
}
|
|
}' | jq
|
|
```
|