AGORA MCP Documentation

# AGORA Instance MCP Server Docs

## Overview
This service is the MCP compatibility adapter for AGORA Instance.

- Service: `agora-mcp-server`
- MCP endpoint: `/mcp`
- Health: `/health`
- Readiness: `/ready`
- Metrics: `/metrics`
- Docs (human): `/docs`
- Docs (raw markdown): `/docs/mcp-docs.md`

## Scope and Boundaries (v1)
- MCP is an adapter layer over AGORA API.
- AGORA API remains the execution and governance source of truth.
- MCP does not directly mutate AGORA domain modules.
- MCP does not replace AGORA native APIs.

Not in v1:
- financial mutation tools (`transfer_funds`, payouts, withdrawals)
- policy mutation tools
- agent provisioning tools
- key rotation/credential mutation tools
- approval decision actions (approve/deny)

## Authentication
### MCP Client -> MCP Server
- Bearer token (`Authorization: Bearer <token>`)
- Token hash is stored at rest.
- Token carries scoped permissions.

### MCP Server -> AGORA API
- Service JWT with scope `mcp:internal`
- Audience and issuer validation is enforced by API internal MCP routes

## Tool Catalog (v1)
Core:
- `list_services`
- `execute_service`
- `get_wallet_balance`
- `list_agents`

Expanded controlled set:
- `get_agent_summary`
- `list_approvals` (read-only)
- `list_departments`
- `create_lead`
- `list_leads`

## Tool Semantics
### execute_service
`execute_service` performs policy/preflight through AGORA API execution path.

Possible outcomes include:
- direct execution success
- `approval_required` (when policy/threshold requires human approval)
- rejected by policy

Approval decision remains in existing AGORA UI/workflow.

## Example MCP Calls (JSON-RPC)
### Initialize
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

### List tools
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

### Call `list_services`
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_services",
    "arguments": {
      "limit": 20,
      "offset": 0
    }
  }
}
```

### Call `execute_service`
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "execute_service",
    "arguments": {
      "service_code": "service.example",
      "input": {},
      "idempotency_key": "ext-req-001"
    }
  }
}
```

## Environment Variables
Core:
- `MCP_PORT`
- `MCP_NODE_ENV`
- `MCP_LOG_LEVEL`
- `MCP_BASE_URL`
- `MCP_DB_URL`
- `MCP_SCHEMA`

Links/UI:
- `MCP_INSTANCE_LABEL`
- `MCP_DOCS_URL`
- `MCP_CLIENT_UI_LOGIN_URL`

API bridge:
- `AGORA_API_BASE_URL`
- `AGORA_API_AUDIENCE`
- `MCP_SERVICE_JWT_ISSUER`
- `MCP_SERVICE_JWT_AUDIENCE`
- `MCP_SERVICE_JWT_PRIVATE_KEY` or `MCP_SERVICE_JWT_SHARED_SECRET`

Control:
- `MCP_RATE_LIMIT_RPM_DEFAULT`
- `MCP_FEATURE_FLAGS_DEFAULT`
- `MCP_ENABLE_METRICS`

## Operational Notes
- Deploy as independent container/service.
- Keep MCP and API on private network for internal calls.
- Use secret manager (Portainer secrets) for DB credentials and JWT keys.
- Monitor `/ready` and `/metrics`.
- Use pinned image tags for rollback.

## Troubleshooting
### `MODULE_NOT_FOUND` at startup
Check relative imports in nested modules and rebuild image after fixes.

### `403 Missing scope`
Check token scopes and per-tool policy settings in staff UI.

### `approval_required`
Expected behavior for gated actions; approve in AGORA existing approval surfaces.