Connecting AI to Any API

AI agents are getting powerful, but they still face a fundamental challenge: connecting to your existing systems. Modern AI platforms like Claude and GPT support tool calling and protocols like MCP (Model Context Protocol) for discovering and invoking external capabilities—but your backend services speak REST, GraphQL, or legacy SOAP. Bridging this gap typically means writing custom integration code for every service you want to expose.

Runbeam changes this equation. With Harmony's protocol translation capabilities, you can expose any HTTP API to AI agents through MCP without modifying your backend or writing custom adapters.

The AI-to-Backend Integration Problem

Consider a typical enterprise scenario. You have a customer service AI agent that needs to look up order status, check inventory levels, and create support tickets. These capabilities exist in your existing microservices—but they're standard REST APIs that know nothing about MCP or AI agent protocols.

The traditional approach requires building MCP server wrappers around each service, managing authentication and rate limiting separately for AI traffic, maintaining translation logic as both MCP specifications and your APIs evolve, and deploying additional infrastructure to host these custom integrations.

This integration work can take weeks per service—and you end up with brittle, tightly-coupled code that breaks when either side changes.

How Harmony Bridges MCP to HTTP

Runbeam's Harmony gateway acts as a universal translator between AI agents and your backend services. Instead of writing custom code, you configure a pipeline that accepts MCP JSON-RPC requests from AI agents, transforms MCP protocol structures into standard HTTP API calls, applies security policies including IP restrictions, rate limiting, and content validation, forwards requests to your existing HTTP backends, and wraps responses back into MCP format for the AI agent.

The gateway handles all protocol translation declaratively—no code required.

The MCP-to-HTTP Pipeline

The MCP-to-HTTP workload demonstrates a complete bridge between AI agents and standard HTTP APIs.

Architecture Overview

The pipeline accepts MCP-formatted requests on a dedicated endpoint, processes them through a security and transformation chain, and forwards them to any HTTP backend you configure.

MCP Request Format

AI agents send tool calls using MCP's JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": "request-001",
  "method": "tools/call",
  "params": {
    "name": "get_user",
    "arguments": {
      "user_id": "12345"
    }
  }
}

The gateway extracts the method and arguments, transforms them into the format your HTTP API expects, and forwards the request. When your backend responds, the gateway wraps the result back into MCP JSON-RPC format for the AI agent.

Security by Default

The pipeline includes built-in security controls that protect both your AI integration and backend services:

IP Allowlisting restricts access to internal networks only (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and localhost). This prevents unauthorized external access while allowing AI agents running in your infrastructure to connect.

Method Restriction ensures only POST requests are accepted, matching MCP protocol requirements and preventing accidental GET-based information disclosure.

Content Type Validation accepts only application/json payloads, blocking malformed or malicious content types.

Rate Limiting can be added via policy configuration to protect backends from AI agent overload—important since AI systems can generate high request volumes during complex reasoning tasks.

The Transform Layer

Protocol translation happens through JOLT—a declarative transformation language. The transform specification maps MCP fields to your HTTP API format:

[
  {
    "operation": "shift",
    "spec": {
      "jsonrpc": "jsonrpc",
      "id": "id",
      "method": "method",
      "params": {
        "*": "params.&"
      }
    }
  }
]

This declarative approach means changes to your API schema require updating a JSON file, not rewriting and redeploying code. You can create different transforms for different AI-to-API mappings, all managed through configuration.

Example: Exposing a User Service to AI

Let's walk through a concrete example. You have a user management API at api.internal.company.com/users that your AI assistant needs to query.

Step 1: Configure the Pipeline

The pipeline definition connects the MCP endpoint to your backend:

[pipelines.mcp_to_http]
description = "Transform MCP requests to User API calls"
networks = ["http_net"]
endpoints = ["mcp_endpoint"]
middleware = [
    "mcp_security",
    "json_extractor",
    "mcp_transform",
]
backends = ["user_api"]

Step 2: Define the Backend Target

Point Harmony at your existing service:

[targets.user_api]
connection.host = "api.internal.company.com"
connection.port = 443
connection.protocol = "https"
timeout_secs = 30

Step 3: Customize the Transform

Modify the JOLT transform to match your API's expected format. If your user API expects a different structure than MCP provides, the transform handles the mapping automatically.

Step 4: Connect Your AI Agent

Configure your AI agent (Claude, GPT, or any MCP-compatible system) to use the Harmony endpoint as its MCP server. The agent discovers available tools and can immediately start calling your user API through the bridge.

What You Gain

Zero Backend Changes - Your existing HTTP APIs work as-is. No MCP libraries to add, no protocol handling to implement, no new endpoints to deploy.

Centralized AI Access Control - All AI-to-backend communication flows through Harmony, giving you a single point for authentication, rate limiting, and audit logging.

Declarative Protocol Translation - Transform specifications are configuration, not code. Update them without rebuilding or redeploying applications.

Multi-Agent Support - Different AI agents (Claude, GPT, custom LLMs) can share the same bridge infrastructure. The gateway handles MCP protocol variations transparently.

Production-Ready Security - IP allowlisting, content validation, and rate limiting are built in. Add custom policies as your security requirements evolve.

Beyond Simple API Calls

The MCP-to-HTTP pattern extends to more sophisticated scenarios:

Multi-Service Orchestration - Configure multiple backends and route different MCP tool calls to different services based on the method name or arguments.

Response Enrichment - Transform backend responses before returning them to AI agents, adding context or reformatting data for better AI consumption.

Legacy System Integration - Expose SOAP services, XML APIs, or proprietary protocols to AI agents by chaining transforms that convert between formats.

Audit and Compliance - Log all AI-to-backend interactions through Harmony's webhook middleware for compliance requirements or debugging AI behavior.

Getting Started

1. Clone the Example

   git clone https://github.com/runbeam/harmony-examples
   cd harmony-examples/pipelines/mcp-to-http

2. Run the Demo

   The included demo script starts a mock backend and demonstrates the full MCP-to-HTTP flow:

   ./demo.sh

3. Test the Bridge

   Send an MCP request to the bridge endpoint:

   curl -X POST http://127.0.0.1:8090/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": "req-001",
       "method": "tools/call",
       "params": {
         "name": "api_call",
         "arguments": {
           "endpoint": "/users",
           "method": "GET"
         }
       }
     }'

4. Point to Your Backend

   Update config.toml to target your actual HTTP API and customize the JOLT transform to match your schema.

5. Configure Your AI Agent

   Add the Harmony endpoint as an MCP server in your AI platform configuration.

Learn More

• Model Context Protocol Specification
• Harmony Transform Documentation
• Runbeam Workload Library

Ready to connect your AI to your APIs? Start with the MCP-to-HTTP template and have your first integration running in minutes.

The future of AI isn't just smarter models—it's models that can actually do things. Give your AI access to your entire API ecosystem, securely and without writing custom integration code.