Skip to content

MCP (Model Context Protocol)

MCP is the inter-service communication layer for the Lucid platform. Every service exposes a small set of outcome-oriented tools that LLMs can invoke directly, enabling workflow orchestration and external integrations without custom API clients.

Why Lucid Uses MCP

Traditional microservice architectures require clients to know each service's REST API. MCP replaces this with a uniform tool interface:

  • LLMs can call services directly -- The workflow orchestrator calls downstream deployments via MCP tools instead of custom HTTP clients
  • Uniform discovery -- Every service publishes its tools at /.well-known/mcp, so orchestrators and clients discover capabilities automatically
  • Outcome-oriented -- Each service exposes 3-5 high-level tools (not low-level CRUD endpoints), matching how LLMs reason about actions
flowchart TB
    subgraph External["External Clients"]
        CLI["Lucid CLI"]
        SDK["Lucid SDK"]
        Custom["Custom Apps"]
    end

    GW["MCP Gateway<br/><small>OAuth 2.1 (external)<br/>mTLS (internal)</small>"]

    subgraph Services["Lucid Services"]
        V["Verifier<br/><small>/mcp</small>"]
        PII["PII Auditor<br/><small>/mcp</small>"]
        GR["Guardrails<br/><small>/mcp</small>"]
        OBS["Observability<br/><small>/mcp</small>"]
    end

    External --> GW
    GW --> Services

Service Discovery

Every Lucid service publishes MCP tool metadata at /.well-known/mcp:

{
  "name": "lucid-pii-auditor",
  "version": "1.0.0",
  "tools": [
    {
      "name": "run_pii_scan",
      "description": "Scan text for PII entities and return detected types with positions",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "description": "Text to scan for PII" }
        },
        "required": ["text"]
      }
    }
  ]
}

The MCP Gateway periodically polls /.well-known/mcp on all registered services and maintains an aggregated tool catalog. Clients query the gateway for available tools rather than discovering services individually.

MCP Gateway

The MCP Gateway is a federation layer that provides a single entry point to all Lucid MCP tools.

Authentication

Client Type Auth Method Description
External OAuth 2.1 Clients authenticate with an OAuth 2.1 token from the configured issuer
Internal mTLS Service-to-service calls use mutual TLS with platform-issued certificates

How It Works

  1. External client sends an MCP tool call to the gateway with an OAuth 2.1 bearer token
  2. Gateway validates the token and checks tool-level permissions
  3. Gateway routes the call to the appropriate service over mTLS
  4. Service executes the tool and returns the result through the gateway
sequenceDiagram
    participant Client
    participant GW as MCP Gateway
    participant PII as PII Auditor

    Client->>GW: call run_pii_scan(text="...")
    Note over Client,GW: OAuth 2.1 Bearer Token
    GW->>GW: Validate token + permissions
    GW->>PII: call run_pii_scan(text="...")
    Note over GW,PII: mTLS
    PII-->>GW: { entities: [...] }
    GW-->>Client: { entities: [...] }

Per-Service MCP Tools

PII Auditor

Tool Description
run_pii_scan Scan text for PII entities and return detected types with positions
redact_text Redact detected PII from text, returning cleaned output and a redaction map
list_pii_patterns List all configured PII detection patterns and their sensitivity levels

Guardrails Auditor

Tool Description
check_guardrails Run full guardrails check (injection, toxicity, jailbreak) on input text
get_policy_violations Return a list of policy violations for a given text, without blocking

Observability Auditor

Tool Description
get_metrics Retrieve aggregated metrics (latency, token usage, cost) for a time range
get_traces Fetch traces for a session, deployment, or time range

Verifier

Tool Description
list_deployments List all active deployments with status and metadata
create_deployment Create a new deployment from a LucidEnvironment spec
get_deployment_status Get detailed status for a specific deployment
get_passport Retrieve the AI Passport for a deployment or workflow
verify_attestation Verify a TEE attestation quote against hardware roots of trust

MCP in Workflows

In a workflow, the orchestrator LLM calls downstream deployments via MCP tools. During workflow compilation, each downstream node is registered as an MCP tool on the orchestrator:

Tool: call_billing_agent
Description: Route billing inquiries, invoice questions, and payment issues
Input: { "message": "string" }

The orchestrator sees these tools in its context alongside the compiled system prompt. When the LLM decides to route a request, it generates a tool call, which the MCP runtime resolves to an HTTP request to the downstream deployment.

Tools are the only routing mechanism

There is no separate routing layer. The LLM's tool-calling capability is the router. This keeps the architecture simple and makes routing decisions inspectable in standard LLM traces.

Configuration

MCP is enabled by default on all Lucid services. See the Configuration Reference for environment variables controlling MCP endpoints and the gateway.

Next Steps