Elsai MCP

Package: elsai-mcp  v0.1.1

Automatically converts any backend Swagger (OpenAPI) API into a Model Context Protocol (MCP) server, making your existing APIs available as agent tools with minimal configuration.

Installation

pip install --extra-index-url https://core-packages.elsai.ai/root/elsai-mcp/ elsai-mcp==0.1.1

Requirements: Python >= 3.10, mcp, fastmcp

---

MCPFlow

The central orchestrator that parses your Swagger/OpenAPI spec and launches an MCP server.

from elsai_mcp import MCPFlow

mcp = MCPFlow(
    swagger_url="https://petstore.swagger.io/v2/swagger.json",
    base_url="https://petstore.swagger.io/v2",
    auth_config=None,
    transport="sse",
)

mcp.start()

When you call mcp.start(), Elsai MCP:

1. Fetches and parses your OpenAPI/Swagger spec (JSON or YAML)
2. Converts each endpoint into a typed MCP tool
3. Starts a local MCP server your agents can connect to

---

MCPFlow arguments

Argument	Type	Required	Description
swagger_url	str	Yes	URL to the JSON or YAML OpenAPI/Swagger specification
base_url	str	Yes	Base URL where API requests will be sent
auth_config	dict | None	No	Authentication configuration (token-based). Pass None for unauthenticated APIs
transport	str	No	Transport protocol — "sse" (default) or "streamable-http"

---

swagger_url

The URL pointing to your API's OpenAPI/Swagger specification file. This is where Elsai MCP reads the full schema — endpoints, parameters, request bodies, and response shapes — to auto-generate MCP tools.

• Accepts both JSON (.json) and YAML (.yaml / .yml) formats
• Must be publicly reachable or accessible from within your network
• Typically found at /openapi.json, /swagger.json, or /api-docs on your API server

# JSON spec
mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.json",
    base_url="https://api.yourcompany.com",
    auth_config=None,
)

# YAML spec
mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.yaml",
    base_url="https://api.yourcompany.com",
    auth_config=None,
)

---

base_url

The root URL that all API requests are sent to at runtime. This is the actual API server — separate from where the spec is hosted. When an agent calls a converted tool, Elsai MCP constructs the full request URL by appending the endpoint path to this base.

For example, if base_url is https://api.yourcompany.com and the OpenAPI spec defines a GET /users/{id} endpoint, the request goes to https://api.yourcompany.com/users/{id}.

mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.json",
    base_url="https://api.yourcompany.com",   # all tool calls route here
    auth_config=None,
)

Staging vs production

You can point swagger_url at your production spec but set base_url to a staging server — useful for testing tools against real schemas without touching production data.

---

auth_config

Controls how Elsai MCP authenticates requests to your API. Pass a dictionary for token-based authentication, or None for public APIs that require no credentials.

No authentication (public API):

mcp = MCPFlow(
    swagger_url="https://petstore.swagger.io/v2/swagger.json",
    base_url="https://petstore.swagger.io/v2",
    auth_config=None,   # no auth required
)

Bearer token authentication:

mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.json",
    base_url="https://api.yourcompany.com",
    auth_config={"token": "your_bearer_token"},
)

The token is automatically attached as an Authorization: Bearer <token> header on every outbound request. Use environment variables to avoid hard-coding credentials:

import os

mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.json",
    base_url="https://api.yourcompany.com",
    auth_config={"token": os.environ["API_TOKEN"]},
)

---

transport

Determines the communication protocol used between the MCP server and clients (agents, Claude Desktop, or custom integrations).

Value	Protocol	Best for
"sse"	Server-Sent Events	Claude Desktop, standard MCP clients
"streamable-http"	HTTP streaming	Programmatic clients, custom integrations

SSE (default) — use with Claude Desktop and most MCP clients:

SSE keeps an open HTTP connection and pushes events from server to client as they occur. This is the standard transport supported by Claude Desktop and the majority of MCP tooling.

mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.json",
    base_url="https://api.yourcompany.com",
    auth_config=None,
    transport="sse",
)
mcp.start()

Streamable HTTP — use with custom or programmatic clients:

Each request is a standard HTTP call that streams back a response. Simpler infrastructure requirements (no persistent connection), better suited for automated pipelines or environments where SSE is not supported.

mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.json",
    base_url="https://api.yourcompany.com",
    auth_config=None,
    transport="streamable-http",
)
mcp.start()

---

Using with Elsai Agents

from elsai import Agent
from elsai.tools import MCPServerTool

# Connect the agent to the running MCP server
agent = Agent(
    tools=[MCPServerTool(server_url="http://localhost:8000")],
)

result = agent("Get the customer profile for user ID 12345.")
print(result)

---

YAML spec support

Both JSON and YAML OpenAPI specs are supported:

mcp = MCPFlow(
    swagger_url="https://api.yourcompany.com/openapi.yaml",
    base_url="https://api.yourcompany.com",
    auth_config=None,
    transport="sse",
)
mcp.start()

---

What gets converted

Each OpenAPI operation becomes an MCP tool with:

• Tool name derived from operationId (or method + path)
• Description from the operation summary / description
• Input schema from the request body and path/query parameters
• Output schema from the response definition

This means your agents can call any REST API endpoint as if it were a native Python function — no manual tool wrappers needed.