# ConduitMCP
An Elixir implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) specification (version 2025-06-18). Build MCP servers to expose tools, resources, and prompts to LLM applications like Claude Desktop and VS Code extensions.
## Installation
Add to your `mix.exs`:
```elixir
def deps do
[
{:conduit_mcp, "~> 0.4.5"}
]
end
```
Or from GitHub:
```elixir
def deps do
[
{:conduit_mcp, github: "nyo16/conduit_mcp"}
]
end
```
## What's New in v0.4.0
**🚀 Stateless Architecture for Maximum Concurrency**
- Removed GenServer bottleneck - all requests now processed concurrently
- Callbacks simplified - no more state passing/returning
- Config initialized once and stored immutably
- Each HTTP request runs in parallel (limited only by Bandit's process pool)
**⚠️ Breaking Changes**
The API has been simplified. Update your callbacks:
```elixir
# v0.3.0 (old)
def handle_list_tools(state) do
{:reply, %{"tools" => state.tools}, state}
end
# v0.4.0 (new)
def handle_list_tools(config) do
{:ok, %{"tools" => config.tools}}
end
```
See the migration guide below for details.
## Quick Start
### Standalone Server
```elixir
defmodule MyApp.MCPServer do
use ConduitMcp.Server
@tools [
%{
"name" => "greet",
"description" => "Greet someone",
"inputSchema" => %{
"type" => "object",
"properties" => %{
"name" => %{"type" => "string"}
},
"required" => ["name"]
}
}
]
@impl true
def handle_list_tools(_conn) do
{:ok, %{"tools" => @tools}}
end
@impl true
def handle_call_tool(_conn, "greet", %{"name" => name}) do
{:ok, %{
"content" => [%{"type" => "text", "text" => "Hello, #{name}!"}]
}}
end
end
```
Start the server:
```elixir
children = [
# No need to start the server module - it's just functions!
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP, server_module: MyApp.MCPServer},
port: 4001}
]
Supervisor.start_link(children, strategy: :one_for_one)
```
### Phoenix Integration
Add MCP endpoints directly to your Phoenix application:
```elixir
# lib/my_app/mcp_server.ex
defmodule MyApp.MCPServer do
use ConduitMcp.Server
@tools [
%{
"name" => "get_user",
"description" => "Get user information from database",
"inputSchema" => %{
"type" => "object",
"properties" => %{
"user_id" => %{"type" => "string"}
},
"required" => ["user_id"]
}
}
]
@impl true
def handle_list_tools(_conn) do
{:ok, %{"tools" => @tools}}
end
@impl true
def handle_call_tool(_conn, "get_user", %{"user_id" => id}) do
user = MyApp.Accounts.get_user(id)
{:ok, %{
"content" => [%{"type" => "text", "text" => "User: #{user.name}"}]
}}
end
end
```
Add to your router:
```elixir
# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
use MyAppWeb, :router
pipeline :mcp do
# Optional: Add authentication
plug MyAppWeb.Plugs.MCPAuth, enabled: false
end
scope "/mcp", MyAppWeb do
pipe_through :mcp
forward "/", ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer
end
end
```
That's it! No need to add the server to your supervision tree - it's just a module with functions.
See the [Phoenix Integration Example](examples/phoenix_mcp/README.md) for a complete working example with authentication.
## Client Configuration
### VS Code / Cursor
Add to your MCP settings:
```json
{
"mcpServers": {
"my-app": {
"url": "http://localhost:4001/"
}
}
}
```
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"my-app": {
"command": "elixir",
"args": ["/path/to/your/server.exs"]
}
}
}
```
## Migration Guide (v0.3.x → v0.4.0)
Update your callback signatures and return values:
| Callback | v0.3.x | v0.4.0 |
|----------|--------|--------|
| `mcp_init/1` | Required | Removed (use module attributes instead) |
| `handle_list_tools/1` | `handle_list_tools(config)` → `{:reply, result, config}` | `handle_list_tools(conn)` → `{:ok, result}` |
| `handle_call_tool/3` | `handle_call_tool(name, params, config)` → `{:reply, result, config}` | `handle_call_tool(conn, name, params)` → `{:ok, result}` |
| `handle_list_resources/1` | `handle_list_resources(config)` → `{:reply, result, config}` | `handle_list_resources(conn)` → `{:ok, result}` |
| `handle_read_resource/2` | `handle_read_resource(uri, config)` → `{:reply, result, config}` | `handle_read_resource(conn, uri)` → `{:ok, result}` |
| `handle_list_prompts/1` | `handle_list_prompts(config)` → `{:reply, result, config}` | `handle_list_prompts(conn)` → `{:ok, result}` |
| `handle_get_prompt/3` | `handle_get_prompt(name, args, config)` → `{:reply, result, config}` | `handle_get_prompt(conn, name, args)` → `{:ok, result}` |
**Key changes:**
1. No more `mcp_init/1` - use module attributes like `@tools` instead
2. Callbacks receive `conn` (Plug.Conn) as first parameter instead of config
3. Change `{:reply, result, state}` to `{:ok, result}`
4. Change `{:error, error, state}` to `{:error, error}`
5. Error maps now use string keys: `%{"code" => -32000, "message" => "..."}` instead of atoms
6. **Remove server from supervision tree** - it's just functions now!
**Example Migration:**
```elixir
# v0.3.x
defmodule MyApp.MCPServer do
use ConduitMcp.Server
@impl true
def mcp_init(_opts) do
{:ok, %{tools: [...]}}
end
@impl true
def handle_list_tools(config) do
{:reply, %{"tools" => config.tools}, config}
end
@impl true
def handle_call_tool("echo", %{"msg" => msg}, config) do
{:reply, %{"content" => [...]}, config}
end
end
# Supervision tree
children = [
{MyApp.MCPServer, []}, # ← Remove this!
{Bandit, ...}
]
# v0.4.0
defmodule MyApp.MCPServer do
use ConduitMcp.Server
@tools [...] # Define as module attribute
@impl true
def handle_list_tools(_conn) do
{:ok, %{"tools" => @tools}}
end
@impl true
def handle_call_tool(_conn, "echo", %{"msg" => msg}) do
{:ok, %{"content" => [...]}}
end
end
# Supervision tree
children = [
{Bandit, ...} # Just Bandit!
]
```
**Handling Mutable State**
If you need mutable state (e.g., counters, caches), use external mechanisms:
```elixir
# Option 1: ETS (fastest for concurrent reads/writes)
def handle_call_tool(_conn, "increment", _params) do
:ets.update_counter(:my_counter, :count, 1)
count = :ets.lookup_element(:my_counter, :count, 2)
{:ok, %{"content" => [%{"type" => "text", "text" => "Count: #{count}"}]}}
end
# Option 2: Agent/GenServer (for complex state)
def handle_call_tool(_conn, "get_cache", %{"key" => key}) do
value = MyApp.Cache.get(key)
{:ok, %{"content" => [%{"type" => "text", "text" => value}]}}
end
# Option 3: Database (for persistent state)
def handle_call_tool(_conn, "save_data", %{"data" => data}) do
MyApp.Repo.insert(%Data{value: data})
{:ok, %{"content" => [%{"type" => "text", "text" => "Saved!"}]}}
end
```
**Using Connection Context:**
The `conn` parameter provides access to request context:
```elixir
def handle_call_tool(conn, "private_data", _params) do
# Access authentication info
user_id = conn.assigns[:user_id]
# Check headers
auth = Plug.Conn.get_req_header(conn, "authorization")
{:ok, %{"content" => [%{"type" => "text", "text" => "User: #{user_id}"}]}}
end
```
## Features
- Full MCP specification 2025-06-18 implementation
- **Pure stateless architecture - just compiled functions!**
- No GenServer, no Agent, no process overhead
- No supervision tree required
- Maximum concurrency - limited only by Bandit's process pool
- **Flexible authentication** - Bearer tokens, API keys, custom verification
- Dual transport support (Streamable HTTP and SSE)
- JSON-RPC 2.0 compliant
- Support for tools, resources, and prompts
- Connection context access for authentication/headers
- Configurable CORS and authentication
- Phoenix integration support
- Telemetry events for monitoring
- Production ready with comprehensive test coverage
## Authentication
ConduitMCP includes a flexible authentication plug supporting multiple strategies:
### Development (No Auth)
```elixir
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer,
auth: [enabled: false]},
port: 4001}
```
### Static Bearer Token
```elixir
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer,
auth: [
strategy: :bearer_token,
token: System.get_env("MCP_SECRET_TOKEN")
]},
port: 4001}
```
### Static API Key
```elixir
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer,
auth: [
strategy: :api_key,
api_key: "your-api-key",
header: "x-api-key" # Optional, defaults to "x-api-key"
]},
port: 4001}
```
### Custom Verification Function
```elixir
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer,
auth: [
strategy: :function,
verify: fn token ->
case MyApp.Auth.verify_token(token) do
{:ok, user} -> {:ok, user}
_ -> {:error, "Invalid token"}
end
end,
assign_as: :current_user # Optional, defaults to :current_user
]},
port: 4001}
```
### Database Token Lookup
```elixir
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer,
auth: [
strategy: :function,
verify: fn token ->
case MyApp.Repo.get_by(ApiToken, token: token, active: true) do
%ApiToken{user: user} -> {:ok, user}
nil -> {:error, "Invalid or expired token"}
end
end
]},
port: 4001}
```
### MFA (Module, Function, Args)
```elixir
{Bandit,
plug: {ConduitMcp.Transport.StreamableHTTP,
server_module: MyApp.MCPServer,
auth: [
strategy: :function,
verify: {MyApp.Auth, :verify_mcp_token, []}
]},
port: 4001}
# In MyApp.Auth module:
def verify_mcp_token(token) do
# Your verification logic
{:ok, user} | {:error, reason}
end
```
### Using Authenticated User in Tools
```elixir
defmodule MyApp.MCPServer do
use ConduitMcp.Server
@impl true
def handle_call_tool(conn, "get_profile", _params) do
# Access authenticated user from conn.assigns
case conn.assigns[:current_user] do
nil ->
{:error, %{"code" => -32000, "message" => "Not authenticated"}}
user ->
{:ok, %{
"content" => [%{
"type" => "text",
"text" => "User: #{user.name}, Email: #{user.email}"
}]
}}
end
end
end
```
## Testing
```bash
# Run tests
mix test
# Run with coverage
mix coveralls
# Test with curl
curl -X POST http://localhost:4001/ \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
## Documentation
- [Simple Server Example](examples/simple_tools_server/README.md)
- [Phoenix Integration Example](examples/phoenix_mcp/README.md)
- [MCP Specification](https://modelcontextprotocol.io/specification/)
## Requirements
- Elixir 1.18+
- Erlang/OTP 27+
## License
Apache License 2.0
