Fastmcp Openapi Spec
No description available
Ask AI about Fastmcp Openapi Spec
Powered by Claude Β· Grounded in docs
I know everything about Fastmcp Openapi Spec. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
OpenAPI β MCP Server
Convert any OpenAPI specification into an MCP server that AI agents can use. Instead of registering one tool per endpoint (which bloats agent context), this server exposes just two tools:
| Tool | Purpose |
|---|---|
search | Find API endpoints by keyword (searches paths, summaries, descriptions, tags) |
execute | Call any endpoint with automatic Bearer token authentication |
This keeps the agent's context small (~1,200 tokens) regardless of how many endpoints the API has.
How It Works
βββββββββββββββ ββββββββββββββββββββ ββββββββββββ
β AI Agent ββββββΆβ MCP Server ββββββΆβ REST API β
β (Claude, βββββββ βββββββ (Salla) β
β Cursor,..) β β search: query β ββββββββββββ
β β β OpenAPI spec β
β β β execute: proxy β
β β β HTTP + auth β
βββββββββββββββ ββββββββββββββββββββ
- At startup, the server loads
openapi.jsonand indexes all paths in memory search("products")β scans the spec and returns matching endpoints with their parameters, methods, and descriptionsexecute("/products", "GET", parameters={"page": 1})β makes the actual HTTP call to the API, injecting the Bearer token automatically- The agent never sees the full spec β it discovers what it needs on demand
Quick Start
# Install
pip install -e .
# Configure
cp .env.example .env
# Edit .env β set SALLA_API_TOKEN
# Run (stdio for MCP clients like Claude Desktop, VS Code)
python server.py
# Run as HTTP server (for direct agent access)
python server.py streamable-http
Transport Modes
| Mode | Command | Use Case |
|---|---|---|
| stdio | python server.py | MCP clients (Claude Desktop, VS Code Copilot, Cursor) |
| streamable-http | python server.py streamable-http | Direct HTTP access from AI agents, web apps |
| sse | python server.py sse | Server-Sent Events for streaming clients |
HTTP Mode
When running with streamable-http, the server listens on http://0.0.0.0:8000/mcp by default. Configure with environment variables:
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
Configuration
All via environment variables (or .env file):
| Variable | Required | Default | Description |
|---|---|---|---|
SALLA_API_TOKEN | Yes | β | Bearer token for API authentication |
SALLA_BASE_URL | https://api.salla.dev/v2 | API base URL | |
OPENAPI_SPEC_PATH | ./openapi.json | Path to OpenAPI spec file | |
SERVER_HOST | 0.0.0.0 | HTTP server bind address | |
SERVER_PORT | 8000 | HTTP server port | |
API_TIMEOUT | 30 | Request timeout (seconds) |
Using with AI Agents
Claude Desktop / Claude Code
Add to your MCP config (claude_desktop_config.json or .claude.json):
{
"mcpServers": {
"salla-api": {
"command": "python",
"args": ["server.py"],
"cwd": "/path/to/fastmcp-openapi-spec"
}
}
}
Then ask Claude:
"Search for product endpoints and list the first 5 products"
Claude will:
- Call
search("products")β discoversGET /products,POST /products, etc. - Call
execute("/products", "GET", parameters={"limit": 5})β gets the data - Present the results
Direct HTTP Access (for custom agents)
Start the server in HTTP mode:
python server.py streamable-http
Then any AI agent or application can connect using the MCP protocol over HTTP at http://localhost:8000/mcp.
Python agent example (using mcp client SDK):
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
async with streamablehttp_client("http://localhost:8000/mcp") as (r, w, _):
async with ClientSession(r, w) as session:
await session.initialize()
# Discover endpoints
result = await session.call_tool("search", {"query": "orders"})
print(result)
# Execute an API call
result = await session.call_tool("execute", {
"endpoint": "/orders",
"method": "GET",
"parameters": {"page": 1, "limit": 10}
})
print(result)
cURL example (raw MCP-over-HTTP):
# Initialize session
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# Call the search tool
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search","arguments":{"query":"products","limit":5}}}'
VS Code Copilot Agent Mode
Add to .vscode/mcp.json:
{
"servers": {
"salla-api": {
"command": "python",
"args": ["server.py"],
"cwd": "${workspaceFolder}"
}
}
}
Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"salla-api": {
"command": "python",
"args": ["server.py"],
"cwd": "/path/to/fastmcp-openapi-spec"
}
}
}
Agent Workflow Examples
Example 1: Browse products
Agent MCP Server Salla API
β β β
β search("products") β β
ββββββββββββββββββββββββββββββββΆβ β
β [{path:"/products", β β
β method:"GET", ...}] β β
βββββββββββββββββββββββββββββββββ β
β β β
β execute("/products","GET", β GET /v2/products?limit=5 β
β {limit:5}) ββββββββββββββββββββββββββββββΆβ
β β {products: [...]} β
β {status:"success", βββββββββββββββββββββββββββββββ
β data:{products:[...]}} β β
βββββββββββββββββββββββββββββββββ β
Example 2: Create an order
User: "Create an order for customer 123 with product SKU-456"
Agent thinks: I need to find the create order endpoint first.
β search("create order")
β [{path: "/orders", method: "POST", requestBody: {required: ["customer_id", "items"]}}]
Agent thinks: Now I know the endpoint and required fields.
β execute("/orders", "POST", body={"customer_id": 123, "items": [{"sku": "SKU-456", "quantity": 1}]})
β {status: "success", statusCode: 201, data: {id: 789, status: "pending"}}
Agent: "Order #789 created successfully for customer 123."
Example 3: Multi-step investigation
User: "What's the status of order 789 and who placed it?"
β search("order")
β [GET /orders/{id}, GET /orders, POST /orders, ...]
β execute("/orders/789", "GET")
β {data: {id: 789, status: "shipped", customer_id: 123}}
β search("customer")
β [GET /customers/{id}, ...]
β execute("/customers/123", "GET")
β {data: {id: 123, name: "Ahmad", email: "ahmad@example.com"}}
Agent: "Order 789 is shipped. It was placed by Ahmad (ahmad@example.com)."
Adapting for Other APIs
This server works with any OpenAPI 3.x spec. To use it with a different API:
- Replace
openapi.jsonwith your API's spec - Update
.envwith your API's base URL and auth token:SALLA_BASE_URL=https://api.yourservice.com/v1 SALLA_API_TOKEN=your-token - Run
python server.py
The search and execute tools automatically adapt to whatever endpoints are defined in the spec.
Project Structure
server.py β entry point (registers tools, runs transport)
src/
config.py β env vars + OpenAPI spec loading
tools.py β search and execute tool implementations
openapi.json β your API specification
.env.example β configuration template
pyproject.toml β dependencies
License
MIT
