ask-mcp

Model Context Protocol (MCP) client and server for Ruby. Connect to MCP servers via stdio, SSE, or Streamable HTTP transports. Discover tools, resources, and prompts. Or run the other way: expose your own tools as an MCP server over stdio. Supports the full MCP protocol with OAuth 2.1 authentication.

MCP is the industry standard for LLM tool discovery — the same protocol used by Claude Code, Codex, Cursor, GitHub Copilot, and many other AI clients.

gem "ask-mcp"

gem "ask-mcp"

Quick Start

require "ask/mcp"

# Connect to a local MCP server via stdio
client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
client.start

# List available tools
client.tools.each { |name, tool| puts "#{name}: #{tool.description}" }

# Call a tool
result = client.call_tool("read_file", path: "/tmp/test.txt")
puts result

# Clean up
client.stop

Transports

ask-mcp supports three transports:

Transport	Class	When to Use
stdio	Ask::MCP::Transport::Stdio	Local processes (CLI tools, local MCP servers)
SSE	Ask::MCP::Transport::SSE	Remote servers with Server-Sent Events
Streamable HTTP	Ask::MCP::Transport::StreamableHTTP	Remote HTTP servers

# Factory methods for common cases
Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
Ask::MCP.from_sse("https://mcp.example.com/sse")
Ask::MCP.from_http("https://mcp.example.com/mcp")

# Or create explicitly
transport = Ask::MCP::Transport::Stdio.new("ruby", ["server.rb"])
client = Ask::MCP::Client.new(transport, timeout: 30)

Client API

client = Ask::MCP.from_stdio("ruby", ["server.rb"])
client.start

# Discover capabilities
client.tools       # => Hash of name → Ask::MCP::Tool
client.resources   # => Hash of uri → Ask::MCP::Resource
client.prompts     # => Hash of name → Ask::MCP::Prompt

# Call tools and read resources
client.call_tool("tool_name", arg1: "value")
client.read_resource("file:///path/to/file")
client.get_prompt("prompt_name", name: "World")

client.stop

Result Caching

Tools, resources, and prompts are cached after the first request. Calling the method again returns the same cached Hash. To bypass caching, pass no_cache: true to the client constructor.

Cache is automatically invalidated when the server sends notifications/tools/list_changed (or resources/prompts).

Input Validation

ask-mcp validates tool call arguments against JSON Schema when enabled:

client = Ask::MCP::Client.new(transport, validate: true)
client.start

# Raises Ask::MCP::Validator::ValidationError if arguments are invalid
client.call_tool("echo", message: "hello")     # OK
client.call_tool("echo", nonexistent: true)    # Raises error

Or validate directly:

Ask::MCP.validate!(input_schema, arguments)
validator = Ask::MCP::Validator.new(schema)
validator.valid?(args)   # => true/false
validator.validate!(args) # => true or raises ValidationError

Authentication

ask-mcp provides two authentication classes:

Token-based auth:

token = Ask::MCP::Auth::Token.new("my-token")
headers = token.apply({})  # => { "Authorization" => "Bearer my-token" }

OAuth 2.1:

oauth = Ask::MCP::Auth::OAuth.new(
  client_id: "my-client",
  client_secret: "my-secret",
  token_url: "https://auth.example.com/token"
)
oauth.authenticate!
headers = oauth.apply({})

For details, see the Auth Setup Guide.

With ask-agent

Convert MCP tools to Ask::Tool instances for use with Ask::Agent:

client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
client.start

# Via Tool#to_ask_tool
client.tools.each { |name, tool| agent.register_tool(tool.to_ask_tool) }

# Via AskTool adapter
wrapped = Ask::MCP::Adapters::AskTool.wrap(client.tools)
wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }

Expose your own tools as a server

Ask::MCP also runs the other way. Ask::MCP::Adapters::ToolServer wraps any collection of duck-typed tools (name, description, call) into MCP definitions, and Server.start_stdio serves them over stdio to any MCP client:

require "ask/mcp"
require "ask-tools-shell"

Ask::MCP::Server.start_stdio(
  name: "my-tools",
  tools: Ask::Tools::Shell::TOOLS.map(&:new)
)

Any MCP client — Claude Code, Cursor, ZCode, your own Ask::MCP::Client — can now discover and call those tools. This is exactly how ask-web-search-mcp and ask-rails-harness-mcp are built.

Architecture

ask-mcp/
├── lib/ask/mcp.rb                         # Entry point, factory methods
├── lib/ask/mcp/client.rb                  # MCP client
├── lib/ask/mcp/server.rb                  # MCP server (start_stdio)
├── lib/ask/mcp/tool.rb                    # Tool model
├── lib/ask/mcp/resource.rb                # Resource model
├── lib/ask/mcp/prompt.rb                  # Prompt model
├── lib/ask/mcp/validator.rb               # JSON Schema validator
├── lib/ask/mcp/native/messages.rb         # JSON-RPC message layer
├── lib/ask/mcp/transport/
│   ├── stdio.rb                           # stdio transport
│   ├── sse.rb                             # SSE transport
│   └── streamable_http.rb                 # Streamable HTTP transport
├── lib/ask/mcp/auth/
│   ├── oauth.rb                           # OAuth 2.1
│   └── token.rb                           # Token auth
└── lib/ask/mcp/adapters/
    ├── ask_tool.rb                        # MCP tool → Ask::Tool
    └── tool_server.rb                     # Ask tools → MCP server