action_mcp.cr

A Crystal port of the server side of the official MCP Ruby SDK mcp 1.7.0 (modelcontextprotocol/ruby-sdk) — it exposes a CRails application as a Model Context Protocol server over the Streamable HTTP transport (stateless, JSON-response mode): JSON-RPC 2.0 initialize / tools/list / tools/call on POST /mcp. The exposed surface is the same ActiveAgent::Tool contract the app's own agents use, plus an agent(... wrapper that turns an ActiveAgent::Base agent into a tool. On top of the wire protocol sits a CRails-only Gateway (Bearer-token API keys with read/write scopes, fixed-window quotas, usage counters for billing, per-call audit events) that has no SDK counterpart. Suite: 28/28 wire oracle (byte-for-byte against the real SDK) + 13/13 gateway/DSL/routes against mcp 1.7.0.

⚠️ EXPERIMENTAL FRAMEWORK, DO NOT USE IN PRODUCTION YET.

Installation

dependencies:
  action_mcp_cr:
    github: OrelSokolov/action_mcp.cr

shards install

Depends on active_support.cr, action_pack.cr and active_agent.cr.

Usage

class CustomerSearch
  include ActiveAgent::Tool
  description "Find customers by name"
  input query : String, limit : Int32?
  ActionMCP.mcp_scope :read                  # default; :write for mutations

  def call : ActiveAgent::ToolResult
    ActiveAgent::ToolResult.ok(Customer.where(name: query).to_json)
  end
end

# config/mcp.cr
class AppMcp < ActionMCP::Server
  server_name "myapp"
  server_version "1.0.0"
  tools CustomerSearch, CreateDeal,                # ActiveAgent::Tool classes
        agent(SupportAgent, "CRM support operator") # agent as a tool
end
ActionMCP.mount = AppMcp
ActionMCP.authenticate { |token| ApiKeys.verify(token) }   # optional
ActionMCP.quota_limit = 10_000
ActionMCP.quota_within = 24.hours

# config/routes.cr
CRails.application.routes.draw do
  mcp "/mcp"    # draws POST + GET + DELETE
end

Feature comparison vs mcp 1.7.0 (ruby-sdk, StreamableHTTPTransport)

JSON-RPC wire protocol

Sessions, streaming, transports

CRails extensions (no SDK counterpart)

Deviations & Crystal-specific notes

• Only the stable legacy lifecycle: stateless, JSON-response mode — no SSE streams, no sessions, no SEP-2575 modern envelope; GET always 405.
• The Gateway (401/403/429, codes -32001/-32002/-32003) is a CRails extension; the SDK has no keys/quotas, so it is not oracle-covered.
• logging/setLevel, completion/* and server-to-client requests answer -32601 (not implemented).
• tools/list is not filtered by key scope — the client sees the full catalog; the gate is on tools/call.
• initialize validation of individual fields responds with a generic -32602 "Invalid params" (the oracle locks only the missing-params case).
• Tool dispatch is compile-time (tools macro, case-dispatcher by the ActiveAgent::Base pattern) — no runtime reflection in Crystal.

Full list with rationale: PLAN.md (Russian).

Testing

crystal spec          # no external services; quotas use the in-memory cache

Oracle: 28 cases recorded with the real mcp 1.7.0 SDK (oracle/cases.rb runs StreamableHTTPTransport stateless under Rack::MockRequest → oracle/expected.yml); spec/oracle_spec.cr replays them 1:1 through ActionMCP::ServerController — byte-for-byte bodies, including inputSchema key order and json_schemer-style validation messages. Gateway/DSL/routes: 13 unit specs. Vendored source of reference: oracle/vendor/gems/mcp-1.7.0/.