Skip to main content
Glama
MCP Agent Platform MVP

MCP Agent Platform MVP

by SuneraUdana

MCP Agent Platform MVP

A deliberately small hybrid monorepo foundation: Fastify owns the public API and MCP gateway boundary, while FastAPI owns authorization policy decisions. PostgreSQL and Redis are provisioned for the next persistence/cache increment.

Layout

  • apps/api: TypeScript Fastify API, agent registry with PostgreSQL and explicit memory fallback, OpenAPI at /docs.

  • services/policy: Python FastAPI policy boundary with explicit in-memory policy rules and secure default-deny.

  • services/tool: deterministic Streamable HTTP MCP server used by the local showcase.

  • demo/gradio_app.py: Gradio client for the governed invocation flow.

  • apps/dashboard: React/Vite operator dashboard for read-only governance overview and audit activity.

  • packages/contracts/schemas/domain.json: shared source-of-truth JSON Schema for domain contracts.

  • infra/docker-compose.yml: PostgreSQL and Redis.

  • docs/mvp-evaluation.md: evidence-based scope, security, performance, and readiness assessment.

Related MCP server: ChatGPT Gateway MCP Nyan

Local run

cp .env.example .env
npm install
npm run build && npm test
# configure the admin tokens in your shell (use long random values)
export ADMIN_API_TOKEN='replace-with-a-long-random-admin-token'
export POLICY_ADMIN_TOKEN='replace-with-a-long-random-policy-admin-token'
export POLICY_SERVICE_TOKEN='replace-with-a-long-random-policy-service-token'
# development fallback (explicit; no database required)
AGENT_REPOSITORY=memory npm run dev:api
# PostgreSQL-backed registry
docker compose -f infra/docker-compose.yml up -d postgres redis
psql "$DATABASE_URL" -f infra/migrations/001_create_agents.sql
psql "$DATABASE_URL" -f infra/migrations/002_create_credentials.sql
psql "$DATABASE_URL" -f infra/migrations/003_create_audit_events.sql
psql "$DATABASE_URL" -f infra/migrations/004_create_policies.sql
psql "$DATABASE_URL" -f infra/migrations/005_add_agent_identity_metadata.sql
AGENT_REPOSITORY=postgres npm run dev:api
python3 -m venv services/policy/.venv
. services/policy/.venv/bin/activate
pip install -r services/policy/requirements.txt
pytest -q services/policy/tests
uvicorn services.policy.app.main:app --reload --port 8000
# separate shell: start the external demo tool
uvicorn services.tool.app.main:app --reload --port 8010
# separate shell: npm run dev:api
# optional dependencies: docker compose -f infra/docker-compose.yml up -d

API health: http://localhost:3000/health; policy health: http://localhost:8000/health. Fastify POST /v1/authorize delegates to the policy service. It returns 503 when the policy service is unavailable and 504 on timeout. The policy service defaults to deny until a matching rule is configured.

Operator dashboard

The API exposes authenticated read-only operator routes:

  • GET /v1/dashboard/summary: agent status/risk counts, audit totals, and the latest ten safe audit events.

  • GET /v1/dashboard/health: API health plus a live policy-service health check.

  • GET /v1/dashboard/agents and GET /v1/dashboard/agents/:id: registry posture, identity metadata, correlated audit timeline, and matching policies.

  • GET /v1/audit?limit=50&agentId=...&toolId=...&decision=allowed&correlationId=...&eventType=authorization&from=...&to=...: authenticated audit explorer filters.

  • GET /v1/policies: policy listing with effect, target, version, status, and rationale metadata.

  • POST /v1/policies/simulate: authenticated policy simulation; the response includes the real decision and an explicit allow/deny explanation.

Both routes require the same ADMIN_API_TOKEN bearer token as the registry routes. Start the API, then run the dashboard in another shell:

export ADMIN_API_TOKEN='replace-with-a-long-random-admin-token'
export API_URL='http://localhost:3000'
npm --workspace @mcp/dashboard run dev

Open http://localhost:5173. Vite proxies API requests and injects the token server-side; the token is never bundled into browser code. For a deployed dashboard, configure the hosting reverse proxy to authenticate /v1/dashboard/* and /v1/audit server-side rather than adding a token to frontend environment variables. The dashboard explicitly handles loading, empty, error, and dependency-unavailable states. It polls the authenticated API for current data; it does not pretend to provide WebSocket or SSE live updates.

The policy service requires Authorization: Bearer <POLICY_SERVICE_TOKEN> on POST /v1/authorize; the API client sends this token from its environment. Keep it server-side and configure the same value for both processes. The policy service returns 503 when service authentication is not configured.

Administrative registry and credential routes require Authorization: Bearer $ADMIN_API_TOKEN. Policy list/create routes require Authorization: Bearer $POLICY_ADMIN_TOKEN; both services fail closed with 503 if their admin token is not configured and return 401 for a missing or invalid token. Keep these tokens server-side and never use them in the Gradio client.

For a local allow rule, start the policy service with a JSON array:

export POLICY_RULES_JSON='[{"policy_id":"demo-weather","effect":"allow","actor_id":"agent-2","tool_id":"weather","action":"invoke","reason":"Demo agent may invoke weather"}]'
uvicorn services.policy.app.main:app --reload --port 8000

Set POLICY_REPOSITORY=postgres with DATABASE_URL to persist policies in PostgreSQL; the migration order is 001 through 005. The default POLICY_REPOSITORY=memory mode is process-local and can be seeded with POLICY_RULES_JSON. POST /v1/policies and GET /v1/policies support controlled demos and require the policy admin token. There is no arbitrary policy-service audit endpoint; the Fastify API records audit events internally. Rules match exact tool/action values and optionally an exact actor. A specific actor match takes precedence over a wildcard actor match; within the same specificity, deny takes precedence over allow. Unmatched requests remain denied.

Test the integrated authorization boundary:

curl -X POST http://localhost:3000/v1/authorize \
  -H "content-type: application/json" \
  -d '{"actorId":"agent-2","toolId":"example-tool","action":"invoke"}'

The API maps its camelCase request to the policy service's snake_case contract and returns the policy AuthorizationDecision.

Agent registry

The registry supports POST /v1/agents, GET /v1/agents, GET /v1/agents/:id, PUT /v1/agents/:id, and POST /v1/agents/:id/deactivate. Create/update requires a non-empty owner, purpose, and riskTier (low, medium, or high). Expired agents are stored as disabled; active records are automatically disabled when they expire. Disabled agents cannot be updated.

The default repository is an in-memory development fallback. PostgreSQL is only selected when AGENT_REPOSITORY=postgres; it fails fast if DATABASE_URL is missing.

JIT credentials

Issue a short-lived credential for an active agent:

curl -X POST http://localhost:3000/v1/agents/agent-2/credentials \
  -H "authorization: Bearer $ADMIN_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"scope":["tools:read"],"ttlSeconds":300}'

The response contains the plaintext secret exactly once. Only its SHA-256 hash is persisted; the API never returns it again. TTL defaults to 15 minutes and is capped at one hour. Credentials require a non-empty scope and an active, non-expired agent.

Revoke a credential:

curl -X POST http://localhost:3000/v1/credentials/<credential-id>/revoke \
  -H "authorization: Bearer $ADMIN_API_TOKEN"

For PostgreSQL, apply infra/migrations/002_create_credentials.sql after the agent migration, then infra/migrations/003_create_audit_events.sql and infra/migrations/005_add_agent_identity_metadata.sql. The memory fallback stores hashed secrets in process memory and is intended only for development; issued credentials disappear on restart.

Audit and protected MCP boundary

Authorization decisions, credential issuance/revocation, and accepted or rejected tool invocations are recorded with a correlation ID. Records include agent/tool/credential IDs, decision, rationale, and safe metadata; plaintext credentials are never written to audit events.

Invoke a tool only with a valid, unexpired, non-revoked credential whose scope contains tool:<toolId> or tools:invoke:

curl -X POST http://localhost:3000/v1/mcp/invoke \
  -H "content-type: application/json" \
  -H "authorization: Bearer <secret-returned-once>" \
  -H "x-correlation-id: demo-invocation-1" \
  -d '{"agentId":"agent-2","toolId":"example-tool","credentialId":"<credential-id>"}'

The boundary executes a configurable Streamable HTTP MCP transport after credential and policy checks. Set MCP_TOOL_URL to an MCP endpoint (the demo uses http://localhost:8010/mcp). The API negotiates one MCP session with initialize, sends notifications/initialized, and invokes the selected tool with tools/call; the invocation is mapped to the tool name and arguments (action, payload fields, and correlationId). JSON-RPC errors, malformed responses, session loss, and timeouts are returned as explicit downstream failures. If unset, the API uses a deterministic local adapter for development. Blank, whitespace-only, and overlong correlation IDs are replaced with generated IDs. Both policy denials and downstream tool failures are audited.

Seed a complete demo flow after starting the API and policy service:

npm --workspace @mcp/api run demo:seed

The command creates an example agent and allow policy, issues a scoped credential, and prints a ready-to-run invocation command. The credential secret is printed once; treat the output as sensitive and revoke the credential after the demo.

For the browser showcase, start the API with MCP_TOOL_URL=http://localhost:8010/mcp, run the seed command, then create a demo virtual environment, install its dependencies, and launch Gradio:

python3 -m venv demo/.venv
demo/.venv/bin/python -m pip install -r demo/requirements.txt
DEMO_API_URL=http://localhost:3000 demo/.venv/bin/python demo/gradio_app.py

The demo environment is separate from services/policy/.venv; do not install the demo dependencies into a different Python interpreter and then launch it with python from another environment. Gradio only starts the browser UI: the API, policy service, and external demo tool must already be running.

Paste the seed output values into the Gradio form. A successful invocation shows the external tool result and correlation ID. Revoke the credential with POST /v1/credentials/<credential-id>/revoke, then repeat the invocation to demonstrate enforcement.

The final validation commands are:

npm run build && npm test
python3 -m pytest -q services/policy/tests
python3 -m json.tool packages/contracts/schemas/domain.json >/dev/null
docker compose -f infra/docker-compose.yml config >/dev/null

See docs/mvp-evaluation.md for the MVP evaluation, benchmark interpretation, security assessment, readiness decision, and recommended research roadmap.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agent clients to safely connect to tools and execution resources through MCP with authorization, approvals, audit, chat-context isolation, SSH/Docker access, and long-running command session tracking.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to govern downstream tool servers by enforcing default-deny authority and attestation on every tool call, with live monitoring, approval, and mid-session revocation.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides a policy-controlled MCP gateway that lets agents invoke tools with explicit policies, bounded execution, scoped visibility, and decision receipts.
      MIT