agoda-com/api-agent

Turn any API into an MCP server. Query in English. Get results even when the API can't.
Point at any GraphQL or REST API. Ask questions in natural language. The agent fetches data, stores it in DuckDB, and runs SQL post-processing. Rankings, filters, and joins over returned data work even if the API doesn't support them.
## What Makes It Different
🎯 Zero config. No custom MCP code per API. Point at a GraphQL endpoint, OpenAPI 3.x spec, or Swagger 2.0 spec. The agent introspects/loads schema automatically.
✨ SQL post-processing. API returns 10,000 unsorted rows? Agent ranks top 10. No GROUP BY? Agent aggregates. Need to join returned tables? Agent combines. The API doesn't need to support it—the agent does.
🔒 Safe by default. Read-only. Mutations blocked unless explicitly allowed.
SQL runs sandboxed: no file, network, or extension access. REST calls stay under the API base URL; GraphQL allows only query operations. Recipes are scoped per target and credentials. Report vulnerabilities via SECURITY.md.
🧠 Recipe learning. Agent samples successful queries into reusable workflows. Ask once, reuse cached pipelines that execute without LLM reasoning. Learned recipes are exposed as tools named r .
## Quick Start
1. Run:
bash
# Direct run (no clone needed)
OPENAIAPIKEY=yourkey uvx --from git+https://github.com/agoda-com/api-agent api-agent
# Or clone
git clone https://github.com/agoda-com/api-agent.git && cd api-agent
uv sync --group dev
Set the OpenAI secret in env:
bash
export OPENAIAPIKEY=yourkey
Direct uvx runs use built-in defaults unless APIAGENTCONFIG points to a
TOML file. A cloned checkout uses api-agent.toml from the repository root by
default.
2. Start local clone:
bash
uv run api-agent
# Or Docker
docker build -t api-agent .
docker run -p 3000:3000 -e OPENAIAPIKEY=yourkey api-agent
3. Add to any MCP client:
json
"mcpServers": {
"rickandmorty": {
"url": "http://localhost:3000/mcp",
"headers": {
"X-Target-URL": "https://rickandmortyapi.com/graphql",
"X-API-Type": "graphql"
4. Ask questions:
"Show characters from Earth, only alive ones, group by species"
"Top 10 characters by episode count"
"Compare alive vs dead by species, only species with 10+ characters"
That's it. Agent introspects schema, generates calls, runs SQL post-processing.
## More Examples
REST API (Petstore):
json
"mcpServers": {
"petstore": {
"url": "http://localhost:3000/mcp",
"headers": {
"X-Target-URL": "https://petstore3.swagger.io/api/v3/openapi.json",
"X-API-Type": "rest"
Your own API with auth:
json
"mcpServers": {
"myapi": {
"url": "http://localhost:3000/mcp",
"headers": {
"X-Target-URL": "https://api.example.com/graphql",
"X-API-Type": "graphql",
"X-Target-Headers": "{\"Authorization\": \"Bearer YOURTOKEN\"}"
## Reference
### Headers
| Header | Required | Description |
| X-Target-URL | Yes | GraphQL endpoint OR OpenAPI/Swagger spec URL |
| X-API-Type | Yes | graphql or rest |
| X-Target-Headers | No | JSON auth headers, e.g. {"Authorization": "Bearer xxx"} |
| X-Passthrough-Headers| No | JSON array of header names to copy from this MCP request onto outbound API calls (merged after X-Target-Headers) |
| X-API-Name | No | Override tool name prefix (default: auto-generated) |