api-agent

API Agent turns any GraphQL or REST API into an MCP server that can be queried in natural language. It introspects the API schema, then executes user questions by generating targeted queries, performing SQL-style post-processing (ranking, filtering, joins) on the retrieved data, and caching successful query pipelines for reuse. This enables capabilities like selecting top results, aggregations, and cross-endpoint joins even when the underlying API lacks native support. To use it, run the server through uvx (Python) or your chosen deployment method, point an MCP client at the server, and configure headers to specify the target API via X-Target-URL and X-API-Type. Tools exposed by the server include per-API core tools named after the API prefix (e.g., <prefix>_query and <prefix>_execute) as well as dynamic recipe tools once learned.

Prerequisites:

• Python 3.11+ installed on your system
• Access to the internet to fetch dependencies
• An OpenAI API key or compatible LLM provider key

1. Install Python dependencies (recommended in a virtual environment):

• python -m venv venv
• source venv/bin/activate # on macOS/Linux
• .\venv\Scripts\activate # on Windows
• pip install uvx openai

2. Clone or obtain the API Agent package:

• git clone https://github.com/agoda-com/api-agent.git
• cd api-agent

3. Run directly via uvx (example with environment variable):

• OPENAI_API_KEY=your_key uvx --from git+https://github.com/agoda-com/api-agent api-agent

4. Alternative: use Docker (build and run):

• git clone https://github.com/agoda-com/api-agent
• docker build -t api-agent .
• docker run -p 3000:3000 -e OPENAI_API_KEY=your_key api-agent

5. For MCP clients, prepare an MCP configuration JSON referencing the server endpoint and required headers (see README for header examples).

Tips and caveats:

• The API Agent operates in read-only mode by default; mutations are blocked unless explicitly allowed via configuration.
• Ensure X-Target-URL points to the GraphQL endpoint or OpenAPI spec and X-API-Type is either graphql or rest.
• If you need advanced query capabilities, you can rely on SQL post-processing to perform rankings, filters, and JOINs across multiple endpoints.
• The system caches successful recipes and queries to accelerate future requests; monitor and manage cached pipelines as needed.
• When using tokens or credentials, securely pass them via X-Target-Headers rather than embedding in headers directly.