API Reference ex_mcp v#1.0.0-rc.1

ExMCP - Complete Elixir implementation of the Model Context Protocol.

Facade for the Agent Client Protocol (ACP).

Behaviour for adapting non-native CLI agents to ACP.

GenServer bridge between ACP clients and non-native CLI agents.

Pure ACP event builders for agent adapters.

ExMCP.Transport implementation that delegates to an AdapterBridge.

Adapter for Claude Code using the Claude Agent SDK process protocol.

Pure Claude SDK message to ACP message mapping.

Pure helpers for Claude Code's SDK-flavoured stream-json protocol.

Pure helpers for Claude Code's SDK session store.

Pure Claude tool-use to ACP tool-call metadata conversion.

Adapter for Codex CLI using codex app-server persistent mode.

Pure config and mode helpers for the Codex ACP adapter.

Pure event-mapping helpers for the Codex ACP adapter.

Pure session and thread helpers for the Codex ACP adapter.

Pure slash-command parsing helpers for the Codex ACP adapter.

ACP adapter for the Pi coding agent.

Runtime for building native Elixir Agent Client Protocol agents.

Behaviour for native Elixir ACP agents.

Transport behaviour for ACP agent runtimes.

In-memory ACP transport for tests and local integration.

Server-side stdio transport for ACP agents.

Pure helpers for ACP capability maps.

GenServer client for the Agent Client Protocol (ACP).

Default ACP handler that collects events and denies permissions.

Behaviour for handling ACP session events and agent requests.

Pure JSON-RPC 2.0 envelope builders for ACP messages.

Pure normalization and validation for ACP session lifecycle parameters.

Small pure map helpers used by ACP protocol, client, agent, and adapters.

Pure helpers for ACP _meta extension placement.

Pure normalizers for ACP name/value list shapes.

Small functional queue core for ACP adapter prompt backlogs.

ACP-specific message encoding.

Helpers for the public ACP agent registry.

Type specifications and builder functions for the Agent Client Protocol (ACP).

Behaviour for implementing approval handlers in MCP clients.

MCP Authorization support for OAuth 2.1 with PKCE.

OAuth 2.1 Authorization Server Metadata Discovery (RFC 8414).

RFC 7523 Section 2.2 — JWT client assertions for private_key_jwt authentication.

OAuth Client ID Metadata Document support for MCP authorization.

This module implements the standard MCP specification.

Full 401 -> discovery -> auth orchestrator for MCP OAuth.

Client-side enterprise SSO orchestrator for MCP.

Handles authorization-related errors and triggers appropriate OAuth flows.

Full OAuth 2.1 authorization code flow with PKCE for MCP.

HTTP client functionality for OAuth 2.1 requests.

ID-JAG (Identity JWT Authorization Grant) creation and validation.

Server-side handler for processing ID-JAG tokens in JWT bearer grants.

Request interceptor that automatically adds authorization headers.

General-purpose JWT module wrapping JOSE for MCP authorization.

RFC 7523 Section 2.1 — JWT Bearer Grant.

OAuth 2.1 flow implementations for MCP authorization.

OpenID Connect Discovery support for MCP authorization.

PKCE (Proof Key for Code Exchange) implementation for OAuth 2.1.

OAuth 2.0 Protected Resource Metadata Discovery (RFC 9728 - Draft).

Behaviour for pluggable OAuth/auth providers in MCP transports.

OAuth 2.1 authorization provider with PKCE, PRM discovery, and scope step-up.

Static token provider for pre-existing bearer tokens.

Maps MCP operations to required OAuth scopes and validates them.

Centralized configuration management for OAuth 2.1 authorization server settings.

OAuth 2.1 Resource Server guard for validating bearer tokens.

RFC 8693 Token Exchange implementation.

Manages OAuth tokens with automatic refresh and expiration tracking.

Client-side OAuth 2.0 Token Revocation (RFC 7009).

Validation functions for OAuth 2.1 parameters and endpoints.

Unified MCP client combining the best features of all implementations.

Callback-based handler for MCP client events.

Connection lifecycle management for ExMCP client.

This module provides ExMCP extensions beyond the standard MCP specification.

Default elicitation handler for MCP clients.

Enhanced error formatting and actionable guidance for MCP.

This module implements the standard MCP specification.

Interactive terminal handler for MCP client events.

Middleware pipeline for cross-cutting concerns in the ExMCP client.

Prompt operations for ExMCP client.

Resource operations for ExMCP client.

Tool operations for ExMCP client.

Request/response processing for ExMCP client.

Response normalization and transformation utilities for MCP.

GenStateMachine implementation for ExMCP.Client.

State-specific data structures for the ExMCP client state machine.

Common data shared across all states.

State data for connecting state.

State data for disconnected state.

State data for handshaking state.

State data for ready state.

State data for reconnecting state.

State transition logic and guards for the ExMCP client state machine.

Shared type definitions for ExMCP.Client modules.

Configuration builder for ExMCP clients.

Raised when client operations fail

Raised when MCP connection fails

A behaviour for handling user consent for accessing external resources.

A consent handler that prompts the user for consent via the command line. Suitable for interactive stdio transport sessions.

A consent handler that denies all requests for external resource access. This is the default, production-safe handler.

A consent handler for web applications.

Content handling utilities for MCP messages.

Smart constructors and builder patterns for ExMCP content creation.

Content protocol for ExMCP - type-safe content handling system.

Content sanitization utilities for MCP content.

Schema validation for MCP content.

Security scanning utilities for MCP content.

Content transformation utilities for MCP content.

Content validation and transformation utilities for ExMCP.

GenServer-based validator registry that replaces Process dictionary usage.

Error types and utilities for ExMCP.

Errors related to MCP protocol violations.

Errors that occur during resource operations.

Errors that occur during tool execution.

Errors related to transport layer issues.

Errors related to input validation.

Feature flag system for controlling rollout of new MCP features.

Helper macros and functions for common MCP patterns in ExMCP.

HTTP Plug for MCP (Model Context Protocol) requests. Compatible with Phoenix and Cowboy servers.

Pure request/response decisions for ExMCP.HttpPlug.

Server-Sent Events handler with backpressure control.

Internal utilities for safe atom handling.

This module implements the standard MCP specification.

A GenServer and ETS-based cache for user consent decisions.

Small pipe-friendly helpers for building protocol maps.

Centralized security configuration management with validation.

Core message processing abstraction for ExMCP.

Connection struct representing an MCP message processing context.

Plug for DNS rebinding protection.

Serves a JSON Web Key Set (JWKS) for token signature verification.

Serves Protected Resource Metadata per RFC 9728.

Plug for validating and extracting the MCP-Protocol-Version header.

Server-side token introspection endpoint (RFC 7662).

Server-side token revocation endpoint (RFC 7009).

Progress tracking for MCP 2025-06-18 specification compliance.

Raised when prompt operations fail

JSON-RPC 2.0 and MCP-specific error codes.

Processes JSON-RPC requests for MCP servers.

Manages tracking of pending requests and cancellations for MCP servers.

Utility module for building JSON-RPC 2.0 responses in MCP.

Handles protocol version negotiation during the MCP initialization phase.

Registry for managing tools, resources, and prompts in ExMCP.

Convenience functions for reliability features.

Circuit breaker GenServer wrapper.

Pure circuit-breaker state machine used by ExMCP.Reliability.CircuitBreaker.

Health check system for MCP clients and servers.

Retry logic with exponential backoff for MCP operations.

Supervisor for reliability components in ExMCP.

Wrapper process that integrates reliability features for MCP clients.

Raised when resource operations fail

Structured response types for MCP operations.

Handles Cross-Origin Resource Sharing (CORS) logic.

Manages user consent for various operations.

Handles token processing and sanitization of requests.

Handles request and response validation, including transport layer security configurations.

Public server-side helpers for running MCP servers.

Helper module to build server capabilities.

Modern DSL for defining MCP server primitives next to their handlers.

Response helpers for the modern server DSL.

This module implements the standard MCP specification.

This module provides ExMCP extensions beyond the standard MCP specification.

Transport-aware process for ExMCP.Server.Handler modules.

Server-side SSE session manager for bidirectional MCP communication.

STDIO transport server for MCP protocol.

DSL for defining MCP tools in server handlers.

Validates AST nodes to ensure they are safe for evaluation.

Simplified tool builder that reduces metaprogramming complexity.

Runtime representation of a tool definition.

Helper functions for building tool responses and working with schemas.

Runtime tool registry that manages tool definitions and handlers.

Normalizes tool responses to comply with MCP specification.

Simplified tool definition DSL that reduces metaprogramming complexity.

Transport configuration and lifecycle management for ExMCP servers.

Session management for streamable HTTP connections.

Maps GitHub paths to local paths for MCP specification files.

GitHub API client for fetching MCP specification files.

Manages sync metadata for MCP specification files.

Launcher module for STDIO servers that handles Mix.install output.

Task struct and state machine validation for MCP Tasks (2025-11-25).

Telemetry integration for ExMCP.

Custom test case for ExMCP with MCP-specific testing utilities.

Custom assertions for MCP protocol testing.

Test data builders and generators for ExMCP.

Mock MCP server implementation for testing.

Mock transport implementation that connects to MockServer.

Generates valid test values from JSON Schema definitions.

Raised when tool operations fail

Behaviour definition for MCP transport implementations.

Standardized error handling for MCP transports.

This module implements the standard MCP specification.

HTTP server transport for MCP with security and CORS support.

Example HTTP server configuration that includes protocol version validation.

Local BEAM transport for ExMCP.

Transport wrapper that adds circuit breaker protection to any MCP transport.

Server-Sent Events client for the Streamable HTTP transport.

Standardized security error handling across transports.

Transport-layer security interceptor that enforces MCP security policies.

This module implements the standard MCP specification.

In-memory transport for testing purposes.

Transport abstraction layer with fallback mechanisms.

Type definitions for the Model Context Protocol.

Type definitions for MCP protocol version 2024-11-05.

Type definitions for MCP protocol version 2025-03-26.

Type definitions for MCP protocol version 2025-06-18.

Type definitions for MCP protocol version 2025-11-25.

Validates MCP tool names according to the 2025-11-25 specification.

Test support module for transport-related testing utilities.

BEAM transport test helper with SecurityGuard integration.

HTTP transport test helper with SecurityGuard integration.

Stdio transport test helper with SecurityGuard integration.

Runs an ACP agent that exercises the stable protocol surface for interop tests.

Runs a minimal stdio ACP agent for cross-language interop tests.

Checks test files for @tag :skip annotations.

Mix task to run a stdio MCP server for interop testing.

Syncs MCP specification documentation from the upstream GitHub repository.

Mix task to run a stdio MCP server for testing and development.

Cleans up stray processes and ports left over from crashed tests.

Run specific test suites for ExMCP.

List and describe test tags used in ExMCP.