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)<br/>Agent auth (SPIFFE + OAuth)</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
Agent-to-MCP JWT Assertion (RFC 7523) Agents authenticate to MCP servers using their SPIFFE-SVID as a JWT client assertion -- no shared secrets
Agent OBO Token Exchange (RFC 8693) For on-behalf-of scenarios, the sidecar performs RFC 8693 token exchange to obtain a composite token carrying both agent and user identity before calling the MCP server

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: [...] }

MCP Server Auth Discovery

When an MCP tool is installed from the App Catalog, Lucid auto-discovers the server's auth requirements using RFC 9728 (Protected Resource Metadata). This eliminates manual credential configuration for MCP servers that advertise their auth needs.

Discovery Flow

  1. Check inherited credentials -- Before any network calls, Lucid checks for scoped credentials (org → workspace) via the credential inheritance cascade. If an inherited credential with sharing_mode: enforce exists for this MCP server's service, DCR is skipped entirely and a derived CredentialRoutingRule is created pointing to the inherited credential. If sharing_mode: inherit is set, the inherited credential is noted as a fallback but DCR proceeds normally.
  2. On install, Lucid fetches the MCP server's /.well-known/oauth-protected-resource metadata endpoint (RFC 9728).
  3. If the server advertises authorization metadata, Lucid auto-registers the agent as an OAuth client via RFC 7591 (Dynamic Client Registration).
  4. A CredentialRoutingRule is automatically created with injection_method: client_credentials targeting the MCP server's token endpoint.
  5. The resource indicator (RFC 8707) is stored for audience binding, preventing confused-deputy attacks where a token issued for one service is replayed against another.
  6. Discovered metadata (authorization_servers, token_endpoint, scopes_supported) is persisted in AppCatalogEntry.mcp_metadata.

Servers that do not expose RFC 9728 metadata skip discovery gracefully -- no errors are raised, and existing manual credential flows (API keys, OAuth via the Connect modal) continue to work as before.

What Gets Stored

Field Source Purpose
authorization_servers RFC 9728 response AS endpoints for token requests
token_endpoint AS metadata Where the sidecar obtains access tokens
scopes_supported AS metadata Available scopes for the MCP server
resource RFC 8707 indicator Audience binding to prevent token misuse
client_id RFC 7591 registration response Agent's registered client ID at this AS

Credential Inheritance

Before an agent installs an MCP tool, the platform checks whether a ScopedCredential already exists for that service at org or workspace scope. This is the credential inheritance check — it ensures that credentials configured centrally by admins are automatically applied to agent installs without requiring every agent owner to re-authenticate.

Sharing Modes

Mode Behavior at Install Time
enforce DCR is skipped. A CredentialRoutingRule is created pointing to the inherited credential. The agent cannot connect a different credential for this service.
inherit The inherited credential is noted as a fallback. DCR still runs (the agent gets its own OAuth client). If DCR succeeds, the agent's own credential takes precedence; if it fails, the inherited one is used.
isolated Credential is not visible to child scopes. No inheritance occurs.

Tool Enforcement

Org and workspace admins can also set tool-level policies that cascade to all agents in scope:

Policy Effect
required The wizard pre-installs the tool for every agent. Agents cannot remove it.
available Tool is in the catalog for agents to optionally install.
blocked Tool is hidden from the agent wizard. Any attempt to install it is rejected.

The /v1/scoped-tools/effective?agent_id={id} and /v1/scoped-credentials/effective?agent_id={id} endpoints resolve the full cascade and return the effective policy for each tool and service.

See the Credentials Guide for the full install flow, YAML examples, and API reference.

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

LLM Judge 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