Evolith Architecture Governance

@beyondnet/evolith-mcp

Evolith MCP Gateway — First-Class Model Context Protocol Server

Bilingual navigation: Versión en Español

Decouples the MCP server from the CLI. It is a first-class product that exposes the MCP tools as a Gateway talking to @beyondnet/evolith-core (the reusable business-logic layer), instead of shelling out to CLI subprocesses.

---

Table of contents

1. Architecture diagram
2. Transports
3. Installation and configuration
4. Authentication
5. Available tools (55)
6. Available resources (12 + dynamic)
7. Available prompts (8)
8. Mutative operations
9. Internal architecture
10. Agent use cases
11. Client configuration
12. SmartCLI integration
13. Extension guide
14. Observability
15. Good practices
16. Troubleshooting

---

Architecture diagram

sequenceDiagram

participant Agent as "AI Agent (Cursor, Claude Desktop, Custom)" participant Gateway as "MCP Gateway @beyondnet/evolith-mcp" participant Core as "Business Logic @beyondnet/evolith-core" participant FS as "File System" participant Git as "Git"

Note over Agent,Gateway: Transport: stdio (local) or Streamable HTTP (remote)

Agent->>+Gateway: tools/call { name: "evolith-validate", args: { path: "/repo" } }

Gateway->>Gateway: 1. Generate correlationId (evl-xxx) Gateway->>Gateway: 2. Lookup tool in ToolRegistry Gateway->>Gateway: 3. ABAC authorization check Gateway->>Gateway: 4. Start timing + structured log (Pino)

Gateway->>+Core: ValidateSatelliteUseCase.execute({ satellitePath }) Core->>+FS: Read evolith.yaml, rulesets/ FS-->>-Core: Configuration + rule definitions

Core->>+Git: Check ADR history, phase state Git-->>-Core: Phase & commit data

Core->>Core: Evaluate rules (Native + OPA) Core-->>-Gateway: ValidationResult { status, issues }

Gateway->>Gateway: 5. Wrap in SuccessEnvelope { success, data, meta } Gateway->>Gateway: 6. Audit log + completion duration

Gateway-->>-Agent: { content: [{ type: "text", text: "{...}" }] }

Note over Agent,Gateway: All errors wrapped in ErrorEnvelope with EvolithErrorCode

---

Transports

The default port is `3000` (main.ts: env PORT or --port, falling back to 3000). The 49100 used in the examples is an arbitrary value, not the default.

Logs are always written to stderr (Pino), because stdout is reserved for the JSON-RPC stream of the stdio transport.

---

Installation and configuration

Installation

# From the monorepo

npm install @beyondnet/evolith-mcp

Or globally

npm install -g @beyondnet/evolith-mcp

Usage

# stdio (default) — for Cursor, Claude Desktop, etc.

evolith-mcp serve

HTTP — for remote integration

evolith-mcp serve --transport http --port 49100

Environment variables

The binary also accepts the flags --transport/-t, --port/-p, --api-key and --allow-no-auth (HTTP only), as well as the evolith-mcp version subcommand.

---

Authentication

stdio transport

No request authentication is required: the process is local, single-user, and the agent runs it directly. The transport establishes an explicit local session principal (id=local-stdio-session, role=local-session, roles=[local-session, operator], scopes=[read, write]) that is recorded in the audit trail of every call (GT-572).

This is not an authorization bypass: ABAC (native + OPA) is still evaluated on every tools/call with that identity, the deploy tools are still denied in production (they require architect), and every mutative tool still demands the HITL gate { apply, approvalToken }. --allow-no-auth / EVOLITH_MCP_ALLOW_NO_AUTH do not apply to stdio (there is no request authentication to skip); if they are passed together with --transport stdio, the server warns about it on stderr at startup.

HTTP transport

In production (NODE_ENV=production), authentication is mandatory: validateAuth() ignores EVOLITH_MCP_ALLOW_NO_AUTH and rejects every request without a valid credential (401). The value of EVOLITH_API_KEY is an arbitrary secret (any string; no prefix required) compared by equality. It is accepted in either of these two headers:

Authorization: Bearer <EVOLITH_API_KEY>

x-api-key:

/health is public (a liveness probe) and requires no credential.

When an OAuth issuer is configured, /.well-known/oauth-protected-resource (and the path-inserted /.well-known/oauth-protected-resource/ ) is also public: it is the RFC 9728 document an unauthenticated client reads to discover which authorization server to go to, so gating it behind the credential it is trying to obtain would make discovery impossible. It carries no MCP data — only the issuer, the resource identifier and the scope names. A 401 from a protected resource additionally carries a WWW-Authenticate: Bearer resource_metadata="…", scope="…" challenge, which is the discovery mechanism MCP clients must prefer. Without an issuer the endpoint returns 404 rather than publishing a document with an empty authorization_servers.

Client registration never flows through this server: it is a resource server, and the 2026-07-28 revision has clients obtain a client_id from a Client ID Metadata Document (or pre-registration) at the authorization server. Dynamic Client Registration is deprecated and is not implemented here; protected-resource-metadata.spec.ts fails the build if a registration endpoint is ever introduced.

Protocol revisions

The server answers two protocol revisions on the same HTTP endpoint:

Both revisions run through one dispatch, so ABAC (native + OPA), the scope gate, the approval gate and the audit trail are the same code on either path. The 2025-11-25 path is retained because the published SDK still declares it as its latest revision; it is not an alternative design.

On the 2026-07-28 path a state-changing tool answers resultType: "input_required" with an elicitation/create request and an opaque requestState. The client gathers the human's approval and retries the original call — new JSON-RPC id, same parameters, plus requestState and inputResponses. The requestState is sealed with AES-256-GCM and bound to the principal, the tenant, the originating call and a short TTL, so it cannot be replayed across users, calls or time. A caller that already holds an approval may still pass { apply: true, approvalToken } inline and skip the round trip, exactly as on the 2025-11-25 path.

The ApiKeyProvisioningService (below) is an advanced and optional mechanism for issuing keys with an evk_ prefix, a SHA-256 hash and a TTL. It is independent of the startup EVOLITH_API_KEY described here.

API key provisioning

The ApiKeyProvisioningService manages the lifecycle of the keys:

Keys carry scopes: read, write, admin. They are bound to a tenant.

ABAC model

The AbacEvaluator controls which tools each user may invoke, based on their roles:

ABAC codes:

Tool classification (substring heuristic). The internal role sets are DEVELOPER = {developer, qa}, OPERATOR = {operator, sre} and ARCHITECT = {architect, admin}. The read/write/deploy classification of each tool is a heuristic over its name (abac-evaluator.ts): it counts as read if the name contains read/list/get (or does not begin with evolith-); as write if it contains write/replace/run/fix/advance; as deploy if it contains deploy/publish/merge. Because of that heuristic, evolith-phase-advance is classified as write (the advance substring), even though it only proposes the transition. A tool that fits no group is rejected with ABAC-03.

Authentication precedence (HTTP). The guard (mcp-server-auth.ts) evaluates the API key first: if the Authorization: Bearer or the x-api-key heade