API Reference ex_mcp v#0.9.2

ExMCP - Complete Elixir implementation of the Model Context Protocol.

Facade for the Agent Client Protocol (ACP) client.

Behaviour for adapting non-native CLI agents to ACP.

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

ExMCP.Transport implementation that delegates to an AdapterBridge.

Adapter for Claude Code CLI.

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

ACP adapter for the Pi coding agent (badlogic/pi-mono).

GenServer client for the Agent Client Protocol (ACP).

Default ACP handler that collects events and auto-allows permissions.

Behaviour for handling ACP session events and agent requests.

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.

Behaviour for client adapters.

Callback-based handler for MCP client events.

Configuration options for ExMCP.Client implementation switching.

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.

Adapter that wraps the existing GenServer-based ExMCP.Client implementation.

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.

Adapter that wraps the StateMachine implementation to provide the standard ExMCP.Client interface.

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.

Wrapper module that provides a unified interface to different client implementations.

Configuration builder for ExMCP clients.

Macros for generating configuration setter functions to eliminate code duplication.

Enhanced configuration builder for ExMCP clients with reduced code duplication.

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.

Helper functions for creating content objects.

Code generation for the ExMCP.Server DSL.

Shared metadata DSL for Tools, Resources, and Prompts.

Simplified DSL for defining MCP prompts.

Simplified DSL for defining MCP resources.

Simplified DSL for defining MCP tools.

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.

Helper functions for creating ExMCP.Error structs. This module provides backward compatibility for tests.

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.

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.

Centralized security configuration management with validation.

Core message processing abstraction for ExMCP.

Connection struct representing an MCP message processing context.

Unified message dispatcher that eliminates duplication between different handler modes.

Unified message handlers for all MCP methods.

Migration module to transition MessageProcessor to use the unified dispatcher.

Native BEAM service dispatcher for direct process communication within Elixir clusters.

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 for ExMCP.Transport.Beam.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.

High-level server implementation with DSL support.

BEAM transport server for MCP protocol.

Helper module to build server capabilities.

This module implements the standard MCP specification.

This module provides ExMCP extensions beyond the standard MCP specification.

Legacy handler-based server implementation.

Helper module to support the gradual refactoring of ExMCP.Server.

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.

Behaviour and macro for creating MCP services with automatic registration.

Pluggable service registry behaviour for ExMCP.Native service discovery.

Distributed service registry adapter using Horde.

Local service registry adapter using Elixir's built-in Registry.

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.

Circuit breaker implementation for MCP service protection in BEAM transport clustering.

Native BEAM clustering support for distributed MCP servers.

Request-response correlation using Registry for efficient lookups.

Health monitoring for MCP services in BEAM transport clustering.

Load balancer for distributing client connections across MCP service instances.

Observability module for BEAM transport providing metrics collection, health monitoring, distributed tracing, and alerting capabilities.

Network partition detection and healing for BEAM transport clustering.

Serialization/deserialization for BEAM transport.

Distributed service registry for BEAM transport clustering.

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.

Unified BEAM transport for ExMCP, supporting both raw terms and JSON.

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.

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.