Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@APIForge MCP Server list my Yandex Metrika counters"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP-сервер для интеграции API-сервисов с Hermes Agent и другими MCP-клиентами.
Hermes Agent — это AI-агент, который работает с инструментами через MCP (Model Context Protocol). Но для работы с реальными API (Яндекс Метрика, Search Console и др.) нужен прослойка, который:
Генерирует инструменты автоматически из JSON-конфигов API
Управляет аутентификацией (API Key, OAuth 2.0)
Контролирует доступ — какие инструменты доступны агенту
Related MCP server: Any API MCP Server
Hermes Agent (MCP Client)
│
MCP Server (Python SDK)
┌────┴────┐
│ Tools │ ← генерируются из JSON-конфигов
│ Auth │ ← API Key / OAuth 2.0
│ Access │ ← allow/deny по инструментам
└────┬────┘
│
HTTP (httpx)
│
┌────┴────┐
│ Yandex │
│ Google │
│ Custom │
└─────────┘# Установка
cd mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Запуск (STDIO — для Hermes)
python -m apiforge_mcp.server
# Запуск (HTTP/SSE — удалённый доступ)
APIFORGE_TRANSPORT=sse python -m apiforge_mcp.serverФайлы в configs/ определяют доступные API и их параметры:
// configs/yandex_metrika.json
{
"base_url": "https://api-metrika.yandex.net",
"auth": { "type": "oauth" },
"resources": {
"counters_list": {
"path": "/management/v1/counters",
"method": "GET",
"description": "List all counters"
},
"counter_stat": {
"path": "/stat/v1/data",
"method": "GET",
"description": "Get statistics",
"parameters": {
"id": { "type": "integer", "required": true, "description": "Counter ID" },
"metrics": { "type": "string", "required": true, "description": "Metrics" }
}
}
}
}Добавление нового API: просто кладёте JSON-файл в configs/. Инструменты генерируются автоматически.
// configs/access.json
{
"default_role": "readonly",
"tools": {
"allow": ["*"],
"deny": ["secret_*"]
},
"service_tools": {
"yandex_metrika": {
"allow": ["yandex_metrika_*"],
"deny": []
}
}
}Уровни контроля:
Global — правила для всех инструментов
Service — правила для конкретного API
Tool — конкретный инструмент
Приоритет: Tool > Service > Global. Deny всегда побеждает Allow.
# Аутентификация
YANDEX_METRIKA_API_KEY=your_api_key
YANDEX_METRIKA_AUTH_PROVIDER=api_key # или oauth
# Контроль доступа
APIFORGE_DEFAULT_ROLE=readonly # readonly | readwrite | admin
YANDEX_METRIKA_ROLE=readwrite # роль для конкретного сервиса
# Сервер
APIFORGE_TRANSPORT=stdio # stdio | sse
APIFORGE_HOST=127.0.0.1 # для SSE
APIFORGE_PORT=8080 # для SSE
APIFORGE_CONFIGS_DIR=./configs # путь к конфигам# ~/.hermes/config.yaml
mcp_servers:
apiforge:
command: python
args: ["-m", "apiforge_mcp.server"]
env:
YANDEX_METRIKA_API_KEY: ${YANDEX_METRIKA_API_KEY}
APIFORGE_DEFAULT_ROLE: readonly# ~/.hermes/config.yaml
mcp_servers:
apiforge:
url: http://your-server:8080/sse
headers:
Authorization: Bearer ${MCP_TOKEN}Инструменты генерируются автоматически из конфигов:
Инструмент | Описание | Метод |
| Список счетчиков | GET |
| Статистика | GET |
| Цели | GET |
| Хосты | GET |
| Запросы | GET |
| Лог аудита | - |
| Список сервисов | - |
Ресурс | Описание |
| Полное руководство по использованию |
| Документация по конкретному сервису |
| Документация по контролю доступа |
| Документация по аутентификации |
ИИ может читать эти ресурсы через resources/read для получения контекста.
Промпт | Когда использовать |
| Запрос аналитических данных |
| Изучение доступных API |
| Диагностика проблем |
ИИ может загружать эти промпты через prompts/get для получения инструкций.
# Все тесты
pytest tests/ -v
# Линтер
ruff check src/ tests/mcp-server/
├── configs/
│ ├── access.json # Правила доступа
│ ├── yandex_metrika.json # API Яндекс Метрики
│ └── yandex_search_console.json
├── src/apiforge_mcp/
│ ├── server.py # MCP сервер + динамическая генерация
│ ├── auth/
│ │ ├── manager.py # Менеджер аутентификации
│ │ ├── api_key.py # API Key провайдер
│ │ └── oauth.py # OAuth 2.0 провайдер
│ ├── access/
│ │ └── policy.py # Контроль доступа (roles + tools)
│ └── tools/
│ └── registry.py # Реестр инструментов
├── tests/
│ └── test_server.py # 32 теста
├── docs/
│ ├── adr/ # Architecture Decision Records
│ └── AI_REFERENCE.md # Справочник для ИИ
├── README.md # Основная документация
├── ARCHITECTURE.md # Архитектурные решения
├── CHANGELOG.md # История изменений
├── CONTRIBUTING.md # Как вносить вклад
├── SECURITY.md # Политика безопасности
├── RUNBOOK.md # Операционные процедуры
└── pyproject.tomlДинамическая генерация — инструменты создаются из JSON, не хардкодятся
APIForge как transport core — HTTP-запросы через httpx с retry
Многоуровневый контроль доступа — glob-паттерны на 3 уровнях
Асинхронность — все запросы async/await для производительности
Аудит — логирование всех вызовов и отказов
Get the access audit log showing recent API calls and denials.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It states the tool 'Get the access audit log showing recent API calls and denials,' but omits critical details such as whether authentication is required, if results are paginated (the 'limit' parameter suggests pagination), what the response format is, or any rate limiting. The description is too brief to adequately inform an agent about operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Get the access audit log showing recent API calls and denials.' It is concise and without wasted words. While it could include more detail, its brevity does not detract from readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple parameter set and an output schema (though not shown). The description covers the basic purpose adequately. However, it lacks context on authentication, pagination behavior, and expected output structure, which are important for a complete understanding. Given the output schema exists, the description need not detail return values, but other behavioral gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes a single parameter 'limit' with a default value but no description (0% coverage). The tool description does not mention this parameter at all, failing to add any meaning beyond what the schema provides. In a low-coverage scenario, the description should compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves an 'access audit log showing recent API calls and denials.' The name 'get_audit_log' aligns perfectly, and the sibling tools are distinct services (e.g., list_services, yandex_metrika_*), so there is no confusion. The description includes specific content detail ('recent API calls and denials') making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, recommended use cases, or situations where a different tool would be more appropriate. The agent is left to infer context purely from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all configured API services and their available resources.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It states the tool lists 'all configured' services and their 'available resources', implying a read-only operation and a structured response, but does not disclose potential side effects or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 9 words, front-loaded with the core action and resource. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and an output schema (not shown), the description fully covers what the tool does. It is complete given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (0 params, schema coverage 100%), so the description does not need to explain parameters. Baseline for 0 params is 4, and the description is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the resource ('all configured API services and their available resources'), clearly distinguishing it from sibling tools like get_audit_log or yandex_metrika_counters_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. For a simple discovery tool, a brief usage hint would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Yandex Metrika counters
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or side effects. While listing is inherently non-destructive, the description is insufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no wasted words. It is front-loaded and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately covers its basic function. However, it omits any mention of authentication or pagination, but for a simple list operation, this is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description need not add parameter details. With 0 parameters and 100% schema coverage, the baseline is 4, and the description meets this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all Yandex Metrika counters' uses a specific verb and resource, clearly distinguishing it from sibling tools like yandex_metrika_counter_stat or yandex_metrika_goals, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing all counters, but offers no explicit guidance on when to use it versus alternatives or when not to use it. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics for a counter
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It merely says 'Get statistics', implying a read operation but offering no details on authentication needs, rate limits, or potential side effects. The behavioral transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short at one sentence, which is concise but at the expense of completeness. It front-loads the purpose but lacks additional context that would be valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to detail return values. However, it omits critical context such as what time period the statistics cover, whether it's aggregate or detailed, or any limitations. The description is insufficiently complete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters in the input schema, so the baseline is 4. The description adds no parameter information, but none is needed since no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves statistics for a counter, with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like yandex_metrika_counters_list or yandex_metrika_goals, though the tool name provides some context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There are no exclusions, prerequisites, or context provided, leaving the agent without direction on appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List goals for a counter
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only states 'List goals' without mentioning idempotency, rate limits, authentication needs, or side effects. The read-only nature is implied but not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded. However, it is too minimal; it could include more context (e.g., prerequisites, output hint) without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 0 parameters and the presence of an output schema, the description is minimally complete. However, it lacks context about how the counter is specified (likely from a parent context) and does not explain what 'goals' are in Yandex Metrika, leaving the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters, and schema description coverage is 100%. The description adds no parameter meaning, but there are no parameters to document. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List goals for a counter' clearly states the action (list) and the resource (goals for a counter). It is specific but does not explicitly differentiate from sibling tools like yandex_metrika_counters_list (lists counters) or yandex_metrika_counter_stat (statistics). The scope is implied but not detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no when-not-to-use scenarios. For example, it does not explain how the counter is identified or if this tool should be used after selecting a counter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all verified hosts
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'List', which is a read-only operation. It does not disclose any behavioral traits such as authentication requirements, rate limits, or what constitutes 'verified hosts'. With zero annotation coverage, the description fails to provide sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise, front-loaded, and contains no extraneous information. Every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description is minimally complete. However, given sibling tools exist for related data, additional context about when to use this tool (e.g., 'Use to retrieve all verified hosts for the current user') would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema, and schema description coverage is 100% (vacuously). According to guidelines, 0 parameters warrant a baseline score of 4. The description adds no param semantics because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all verified hosts' uses a specific verb 'List' and clearly identifies the resource 'verified hosts'. It distinguishes itself from sibling tools like get_audit_log or yandex_metrika_counters_list, which deal with different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Since it is a simple list with no parameters, usage is implied, but there is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get search queries for a host
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Get', which implies a read operation, but does not disclose whether it reads from cache, requires authentication, rate limits, or any side effects. The description is insufficient for understanding behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks critical information needed for correct invocation. It is not appropriately sized for the complexity implied by the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered, but the missing parameter for host selection and lack of behavioral context make the description incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameters, leaving description with no opportunity to add param details. Baseline is 4 for 0 parameters, but the description fails to explain how the host is determined or what the output represents, reducing its added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Get search queries for a host', which is a clear verb+resource combination. However, it does not specify how the host is identified (no parameters), making the purpose somewhat vague and potentially confusing for an agent without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like 'yandex_webmaster_hosts' or 'get_audit_log'. No usage context or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: audit log, service listing, Yandex Metrika operations (list counters, get stats, list goals), and Yandex Webmaster operations (list hosts, get search queries). No overlapping functionality.
Naming conventions are inconsistent. Generic tools use verb_noun (get_audit_log, list_services) but Yandex tools use a reversed pattern (yandex_metrika_counters_list, yandex_metrika_counter_stat) with mixed singular/plural forms. Two distinct styles coexist.
With 7 tools, the count is appropriate for a focused server that combines generic API management with specific Yandex services. It's slightly limited but not excessive.
The tool surface is incomplete for the stated domain. Generic tools only provide audit and listing, missing CRUD operations. Yandex Metrika and Webmaster tools offer read-only operations (list, get stats, list goals) but lack create, update, delete, and other management actions.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mlenkov/apiforge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
