API Agent

MCP数据服务

提供方 agoda-com

数据服务 stdio · 本地进程 Token 社区 / 第三方
查看接入方式

将任何API转换为MCP服务器,通过自然语言查询获取结果,支持SQL后处理。

一句话选型结论

按资料字段整理

API Agent 属于数据服务类 MCP 服务器,stdio · 本地进程,Token,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类数据服务 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 273 仓库热度,无公开仓库时显示未标注
工具数 2 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

数据服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量2暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

API代理Python本地部署自然语言查询SQL处理GraphQLRESTAPI

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
docker run -p 3000:3000 -e OPENAI_API_KEY=your_key api-agent

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 2 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
数据库查询

用自然语言查库、取数,不用手写 SQL。

数据同步与清洗

把多来源数据拉到一处做整理。

报表取数

按口径快速拉出统计结果。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 2 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在数据服务场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
API Agent当前 2 stdio · 本地进程 本地部署 有 2026-05-17
Memory 9d25f64e 9 未标注 未标注 无 2026-05-17
Getzep MCP 9 stdio · 本地进程 本地部署 有 2026-05-17
anything-llm 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Prisma MCP Server 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Astr Bot 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

数据服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方agoda-com上游标注的维护方 agoda-com
分类数据服务本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

7.9 KB
来自项目仓库与上游目录的原文,未做删改

API代理

将任何API转换为MCP服务器。用英语查询。获取结果—即使API不能。

指向任何GraphQL或REST API。用自然语言提问。代理获取数据,将其存储在DuckDB中,并运行SQL后处理。排名、筛选、JOIN工作 即使API不支持它们.

是什么让它与众不同

🎯 零配置。 API没有自定义MCP代码。指向GraphQL端点或OpenAPI规范——模式会自动反思。

✨ SQL后处理。 API返回10000个未排序的行?代理商排名前十。没有分组依据?试剂聚集。需要跨端点的JOIN吗?代理组合。

🔒 默认情况下是安全的。 只读。除非明确允许,否则突变被阻止。

🧠 食谱学习。 成功的查询将成为缓存管道。无需LLM推理即可立即重用。

快速开始

1.运行(选择一个):```bash

Direct run (no clone needed)

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

Or clone & run

git clone https://github.com/agoda-com/api-agent.git && cd api-agent
uv sync && OPENAI_API_KEY=your_key uv run api-agent

Or Docker

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


**2.向任何MCP客户端添加:**```json
{
"mcpServers": {
"rickandmorty": {
"url": "http://localhost:3000/mcp",
"headers": {
"X-Target-URL": "https://rickandmortyapi.com/graphql",
"X-API-Type": "graphql"
}
}
}
}

3.提问:

  • “显示来自地球的角色,只显示活着的角色,按物种分组”
  • “按剧集数排名前10的角色”
  • “按物种比较活的和死的,只有具有10+个字符的物种”

就是这样。代理内省模式,生成查询,运行SQL后处理。

更多示例

REST API(Petstore-OpenAPI 3.x):```json
{
"mcpServers": {
"petstore": {
"url": "http://localhost:3000/mcp",
"headers": {
"X-Target-URL": "https://petstore3.swagger.io/api/v3/openapi.json",
"X-API-Type": "rest"
}
}
}
}


**REST API(Petstore-Swagger 2.0):**```json
{
"mcpServers": {
"petstore": {
"url": "http://localhost:3000/mcp",
"headers": {
"X-Target-URL": "https://petstore.swagger.io/v2/swagger.json",
"X-API-Type": "rest"
}
}
}
}

您自己的带有auth的API:```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 YOUR_TOKEN\"}"
}
}
}
}


______________________________________________________________________

## 参考

### 标头

|标题|必填|描述|
| ---------------------- | -------- | ---------------------------------------------------------- |
| `X-Target-URL` |是| GraphQL端点或OpenAPI/Swagger规范URL(3.x和2.0)|
| `X-API-Type` |是的| `graphql` 或 `rest` |
| `X-Target-Headers` |否|JSON身份验证标头,例如。 `{"Authorization": "Bearer xxx"}` |
| `X-API-Name` |否|覆盖工具名称前缀(默认:自动生成)|
| `X-Base-URL` |否|覆盖REST API调用的基本URL|
| `X-Allow-Unsafe-Paths` |否|包含JSON数组的标头字符串 `fnmatch` 地球仪(`*`, `?`)用于POST/PUT/DELETE/PATCH|
| `X-Poll-Paths` |否|包含JSON轮询路径模式数组的标头字符串(启用轮询工具)|
| `X-Include-Result` |否|包括完全无上限 `result` 输出字段|

#### 标题值示例

`X-Allow-Unsafe-Paths` 和 `X-Poll-Paths` 使用相同的转义格式:JSON数组编码为头字符串。

**MCP配置(JSON):**```json
{
"headers": {
"X-Allow-Unsafe-Paths": "[\"/search\", \"/api/*/query\", \"/jobs/*/cancel\"]",
"X-Poll-Paths": "[\"/search\", \"/trips/*/status\"]"
}
}

X-Allow-Unsafe-Paths 模式示例:

  • "/search" 精确路径
  • "/api/*/query" 一个通配符段
  • "/jobs/*" 以下任何后缀 /jobs/

X-Poll-Paths 模式示例:

  • "/search" 精确轮询路径
  • "/trips/*/status" 通配符轮询路径

X-Poll-Paths 启用轮询指导/工具; X-Allow-Unsafe-Paths 控制不安全的方法。

逃避快速检查(两个标题相同):

  • 错误: "X-Allow-Unsafe-Paths": "["/search"]"
  • 正确的 "X-Allow-Unsafe-Paths": "[\"/search\"]"

MCP工具

核心工具 (每API 2个):

工具 输入 输出
{prefix}_query 自然语言问题 {ok, data, queries/api_calls}
{prefix}_execute GraphQL: query, variables /休息: method, path,参数 {ok, data}

从URL自动生成的工具名称(例如。, example_query).覆盖 X-API-Name.

配方工具 (动态,随着食谱的学习而添加):

工具 输入 输出
r_{recipe_slug} 平面配方特定参数, return_directly (bool) CSV或 {ok, data, executed_queries/calls}

缓存管道,无LLM推理。查询成功后出现。通过以下方式通知客户 tools/list_changed.

配置

变量 必填 默认 描述
OPENAI_API_KEY 是 - OpenAI API密钥(或自定义LLM密钥)
OPENAI_BASE_URL 否 https://api.openai.com/v1 自定义LLM端点
API_AGENT_MODEL_NAME 否 gpt-5.2 型号(例如gpt-5.2)
API_AGENT_PORT 无 3000 服务器端口
API_AGENT_ENABLE_RECIPES 否 正确 启用配方学习和缓存
API_AGENT_RECIPE_CACHE_SIZE 否 64 最大缓存食谱(LRU驱逐)
OTEL_EXPORTER_OTLP_ENDPOINT 否 - OpenTetry跟踪端点

运作原理```mermaid

sequenceDiagram
participant U as User
participant M as MCP Server
participant A as Agent
participant G as Target API

U->>M: Question + Headers
M->>G: Schema introspection
G-->>M: Schema
M->>A: Schema + question
A->>G: API call
G-->>A: Data → stored in DuckDB
A->>A: SQL post-processing
A-->>M: Summary
M-->>U: {ok, data, queries[]}


## 建筑```mermaid
flowchart TB
subgraph Client["MCP Client"]
H["Headers: X-Target-URL, X-API-Type"]
end

subgraph MCP["MCP Server (FastMCP)"]
Q["{prefix}_query"]
E["{prefix}_execute"]
R["r_{recipe} (dynamic)"]
end

subgraph Agent["Agents (OpenAI Agents SDK)"]
GA["GraphQL Agent"]
RA["REST Agent"]
end

subgraph Exec["Executors"]
HTTP["HTTP Client"]
Duck["DuckDB"]
end

Client -->|NL + headers| MCP
Q -->|graphql| GA
Q -->|rest| RA
E --> HTTP
R -->|"no LLM"| HTTP
R --> Duck
GA --> HTTP
RA --> HTTP
GA --> Duck
RA --> Duck
HTTP --> API[Target API]

堆栈: FastMCP • OpenAI代理SDK • DuckDB


食谱学习

Agent从成功的查询中学习可重用的模式:

  1. 执行 -API通过LLM推理调用+SQL
  2. 提取物 --LLM将跟踪转换为参数化模板
  3. 缓存 -存储由(API、架构哈希)键控的配方
  4. 暴露 --配方成为MCP工具(r_{name})无需LLM即可调用```mermaid
    flowchart LR
    subgraph First["First Query via {prefix}_query"]
    Q1["'Top 5 users by age'"]
    A1["Agent reasons"]
    E1["API + SQL"]
    R1["Recipe extracted"]
    end

subgraph Tools["MCP Tools"]
T["r_get_top_users
params: {limit}"]
end

subgraph Reuse["Direct Call"]
Q2["r_get_top_users({limit: 10})"]
X["Execute directly"]
end

Q1 --> A1 --> E1 --> R1 --> T
Q2 --> T --> X


配方会在架构更改时自动过期。禁用 `API_AGENT_ENABLE_RECIPES=false`.

______________________________________________________________________

## 发展```bash
git clone https://github.com/agoda-com/api-agent.git
cd api-agent
uv sync --group dev
uv run pytest tests/ -v      # Tests
uv run ruff check api_agent/  # Lint
uv run ty check               # Type check

可观测性

集 OTEL_EXPORTER_OTLP_ENDPOINT 以启用OpenTetry跟踪。与Jaeger、Zipkin、Grafana Tempo、Arize Phoenix合作。

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
API Agent 怎么安装?

在客户端按下面的安装命令接入:docker run -p 3000:3000 -e OPENAI_API_KEY=your_key api-agent。装完在客户端配置里引用同一个包或端点。

API Agent 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

API Agent 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

API Agent 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

API Agent 能提供哪些能力?

资料显示约 2 个工具;能力标签包括 API代理、自然语言查询、Python、API集成、GraphQL。具体工具清单以官方文档为准。

API Agent 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

API Agent 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。