Ex Mcp

Standalone Client

# Connect to a stdio-based server
{:ok, client} = ExMCP.Client.start_link(
  transport: :stdio,
  command: ["node", "my-mcp-server.js"]
)

# List available tools
{:ok, tools} = ExMCP.Client.list_tools(client)

# Call a tool
{:ok, result} = ExMCP.Client.call_tool(client, "search", %{
  query: "Elixir programming",
  limit: 10
})

BEAM-Local MCP

For trusted Elixir processes in the same VM, use the BEAM-local transport. It carries MCP-shaped messages as Elixir terms, so local calls avoid JSON encode/decode while still using the normal MCP client/server lifecycle.

defmodule MyToolService do
  use ExMCP.Server.Handler
  use ExMCP.Server.DSL

  tool "ping", "Test tool" do
    run fn _args, state ->
      {:ok, %{content: [%{type: "text", text: "Pong!"}]}, state}
    end
  end
end

{:ok, server} = MyToolService.start_link(transport: :beam)

{:ok, client} =
  ExMCP.Client.start_link(
    transport: :beam,
    server: server
  )

{:ok, tools} = ExMCP.Client.list_tools(client)
{:ok, result} = ExMCP.Client.call_tool(client, "ping", %{})

Fast verification: From the repo root (after mix compile), run mix examples.getting_started for a quick in-process demo of these patterns.

ACP: Control and Build Coding Agents

Use the Agent Client Protocol to control coding agents programmatically or expose an Elixir process as an ACP agent:

# Native ACP agents over stdio (Gemini CLI, Hermes, OpenCode, Qwen Code, etc.)
{:ok, client} = ExMCP.ACP.start_client(command: ["gemini", "--acp"])

# Create a session and send a prompt
{:ok, %{"sessionId" => sid}} = ExMCP.ACP.Client.new_session(client, "/my/project")
{:ok, %{"stopReason" => _}} = ExMCP.ACP.Client.prompt(client, sid, "Fix the failing tests")

# Claude Code via the SDK-compatible adapter
{:ok, client} = ExMCP.ACP.start_client(
  command: ["claude"],
  adapter: ExMCP.ACP.Adapters.ClaudeSDK,
  adapter_opts: [model: "sonnet", cwd: "/my/project"]
)

# Pi coding agent through the ACP-native adapter
{:ok, client} = ExMCP.ACP.start_client(
  command: ["pi"],
  adapter: ExMCP.ACP.Adapters.Pi,
  adapter_opts: [model: "anthropic/claude-sonnet-4", thinking_level: "medium"]
)

# Native Elixir ACP agent over stdio
{:ok, agent} = ExMCP.ACP.start_agent(
  handler: MyApp.AgentHandler,
  agent_info: %{"name" => "my-agent", "version" => "1.0.0"}
)

See the [ACP Guide](docs/ACP_GUIDE.md) for full details.

Transport Performance

| Transport | Latency | Best For | |-----------|---------|----------| | BEAM-local | ~15us | Local Elixir processes in one VM | | stdio | ~1-5ms | Subprocess communication | | HTTP/SSE | ~5-20ms | Web applications, remote APIs |

Documentation

Getting Started

• Quick Start Guide -- Get running in 5 minutes
• Migration Guide -- Version upgrade instructions

Guides

• [User Guide](docs/guides/USER_GUIDE.md) -- Complete feature walkthrough
• [Phoenix Integration](docs/guides/PHOENIX_GUIDE.md) -- Detailed Phoenix/Plug integration
• [DSL Guide](docs/DSL_GUIDE.md) -- Declarative server definitions
• [ACP Guide](docs/ACP_GUIDE.md) -- Agent Client Protocol for controlling coding agents
• [Transport Guide](docs/TRANSPORT_GUIDE.md) -- Transport selection and optimization
• [Configuration](docs/CONFIGURATION.md) -- All configuration options
• [Security](docs/SECURITY.md) -- Authentication, TLS, and best practices
• [Troubleshooting](docs/TROUBLESHOOTING.md) -- Common issues and solutions

Development & API

• [Development Guide](docs/DEVELOPMENT.md) -- Setup, testing, and contributing
• API Documentation -- Complete API reference
• [Architecture](docs/ARCHITECTURE.md) -- Internal design decisions
• Examples -- Real-world patterns

Contributing

Contributions welcome! See the [Development Guide](docs/DEVELOPMENT.md) for setup and testing instructions.

1. Fork the repository
2. Create a feature branch
3. Run make quality to ensure code quality
4. Submit a pull request

License

MIT -- see LICENSE.

Acknowledgments

• The Model Context Protocol and Agent Client Protocol specification creators
• The Elixir community for excellent tooling and libraries
• Contributors and early adopters providing feedback

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: azmaveth
• Source: azmaveth/ex_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.