Active Agent

Appearance

Model Context Protocols (MCP) ​

Connect agents to external services via Model Context Protocol servers. MCP servers expose tools and data sources that agents can use automatically.

Quick Start ​

ruby
class WeatherAgent < ActiveAgent::Base
  generate_with :anthropic, model: "claude-haiku-4-5"

  def forecast
    prompt(
      "What's the weather like?",
      mcps: [ { name: "weather", url: "https://demo-day.mcp.cloudflare.com/sse" } ]
    )
  end
end

Provider Support ​

ProviderSupportNotes
OpenAI✅Via Responses API
Anthropic⚠️Beta
OpenRouter🚧In development
Ollama❌Not supported
Mock❌Not supported

MCP Format ​

ruby
{
  name: "server_name",        # Required: server identifier
  url: "https://server.url",  # Required: MCP endpoint
  authorization: "token"      # Optional: auth token
}

Single Server ​

ruby
class DataAgent < ActiveAgent::Base
  generate_with :anthropic, model: "claude-haiku-4-5"

  def analyze
    prompt(
      "Analyze the latest data",
      mcps: [ { name: "cloudflare-demo", url: "https://demo-day.mcp.cloudflare.com/sse" } ]
    )
  end
end

Multiple Servers ​

ruby
class IntegratedAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4o"

  def research
    prompt(
      "Research the latest AI developments",
      mcps: [
        { name: "cloudflare", url: "https://demo-day.mcp.cloudflare.com/sse" },
        { name: "github", url: "https://api.githubcopilot.com/mcp/", authorization: ENV["GITHUB_MCP_TOKEN"] }
      ]
    )
  end
end

With Function Tools ​

ruby
class HybridAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4o"

  def analyze_data
    prompt(
      "Calculate and fetch data",
      tools: [ {
        name: "calculate",
        description: "Perform calculations",
        parameters: {
          type: "object",
          properties: {
            operation: { type: "string" },
            a: { type: "number" },
            b: { type: "number" }
          }
        }
      } ],
      mcps: [ { name: "data-service", url: "https://demo-day.mcp.cloudflare.com/sse" } ]
    )
  end

  def calculate(operation:, a:, b:)
    case operation
    when "add" then a + b
    when "subtract" then a - b
    end
  end
end

OpenAI ​

OpenAI supports MCP via the Responses API with pre-built connectors and custom servers.

Pre-built Connectors ​

ruby
class FileAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4o"

  def search_files
    prompt(
      input: "Find documents about Q4 revenue",
      mcps: [ { name: "dropbox", url: "mcp://dropbox" } ]  # Pre-built connector
    )
  end
end

Available: Dropbox, Google Drive, GitHub, Slack, and more. See OpenAI's MCP docs for the full list.

Custom Servers ​

ruby
class CustomAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4o"

  def custom_tools
    prompt(
      input: "Use custom tools",
      mcps: [ { name: "github_copilot", url: "https://api.githubcopilot.com/mcp/", authorization: ENV["GITHUB_MCP_TOKEN"] } ]
    )
  end
end

Anthropic ​

Anthropic supports MCP servers via the mcp_servers parameter (beta). Up to 20 servers per request.

ruby
class ClaudeAgent < ActiveAgent::Base
  generate_with :anthropic, model: "claude-haiku-4-5"

  def use_mcp
    prompt(
      message: "What tools are available?",
      mcps: [ { name: "demo-server", url: "https://demo-day.mcp.cloudflare.com/sse" } ]
    )
  end
end

See Anthropic's MCP docs for details.

Native Formats ​

ActiveAgent converts the common format to provider-specific formats automatically. Use native formats only if needed for provider-specific features.

ruby
class OpenAINativeAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4o"

  def native_format
    prompt(
      input: "What can you do?",
      tools: [ {
        type: "mcp",
        server_label: "github",
        server_url: "https://api.githubcopilot.com/mcp/",
        authorization: ENV["GITHUB_MCP_TOKEN"]
      } ]
    )
  end
end
ruby
class AnthropicNativeAgent < ActiveAgent::Base
  generate_with :anthropic, model: "claude-haiku-4-5"

  def native_format
    prompt(
      message: "What can you do?",
      mcp_servers: [ {
        type: "url",
        name: "cloudflare",
        url: "https://demo-day.mcp.cloudflare.com/sse"
      } ]
    )
  end
end

Troubleshooting ​

Server not responding: Verify the URL is correct and accessible from your environment.

Authorization failures: Check token validity, permissions, and expiration.

Tools not available: Ensure the server implements MCP correctly and returns valid tool definitions.