MULTIAGENTS-MCP

Give your MCP client a configurable team of AI agents, persistent jobs, reviewed workflows, and project-specific model combos.

Use your own models through OpenAI-compatible Chat Completions backends. Keep your main assistant in control while specialized agents analyze code, propose changes, review evidence, or handle editorial tasks.

English · Português brasileiro

English

What can you do with it?

• Ask one agent to investigate a problem and another to review the proposed solution.

• Run independent jobs concurrently within per-agent limits, inspect partial output, and retain results between sessions.

• Turn a larger task into explicit workflow steps with acceptance criteria, review gates, and recorded execution evidence.

• Create a model combo for a project without overwriting routes used by another CLI.

• Test individual models inside an existing combo to identify which respond, fail, or return degraded output.

• Use different configured backends for different agents without changing your MCP client's primary model.

You define the team. Agent names, roles, model IDs, providers, fallbacks, and permissions belong to your private configuration. No personal profiles, subscriptions, or author-specific model combos are required.

Project combo management and individual member probes require 0.5.0 or later. Older installations can keep their existing inference-only profiles.

Features

Install from npm

Requires Node.js >=20.11 and a configured backend. In Codex, use:

[mcp_servers.multiagents-mcp]
command = "npx"
args = ["--yes", "--package=multiagents-mcp@^0.6.0", "multiagents-mcp"]

Add the private environment settings shown below, including your agent file, backend URL, credentials, and state directories. The example agent YAML below can be saved directly to your private agent file. Restart or reload the MCP connection after configuration changes.

Or install from source

Requires Node.js >=20.11. CI tests Node 20 and 24.

git clone https://github.com/SanNw/multi-agents-mcp.git
cd multi-agents-mcp
npm ci
npm run build

Copy config/agents.example.yaml to a private location. Replace placeholder model IDs with IDs or aliases accepted by your backend. Rename, add, or remove agents freely:

agents:
  builder:
    route: your-model-id
    role: software_development
    task_kinds: [development]
    description: Proposes code and tests using the context supplied by the client.
    route_strategy: fallback
  reviewer:
    route: your-review-model-id
    role: architecture_and_review
    task_kinds: [architecture]
    description: Reviews architecture, implementation risks, and test evidence.

Supported task kinds are development, architecture, documentation, translation, and philology. If no specialization matches, routing selects the first configured agent. Complex tasks suggest review/implementation/review only when those roles exist.

Example configuration for Codex; use absolute paths and your actual private values:

[mcp_servers.multiagents-mcp]
command = "node"
args = ["/absolute/path/to/multi-agents-mcp/dist/index.js"]

[mcp_servers.multiagents-mcp.env]
AGENTS_CONFIG = "/absolute/path/to/private/agents.yaml"
MULTIAGENTS_BASE_URL = "http://127.0.0.1:8000/v1"
MULTIAGENTS_API_KEY = "your-private-key"
MULTIAGENTS_JOBS_DIR = "/absolute/path/to/private/jobs"
MULTIAGENTS_WORKFLOWS_DIR = "/absolute/path/to/private/workflows"
MULTIAGENTS_COMBOS_DIR = "/absolute/path/to/private/combos"

Other MCP clients use the same command, arguments, and environment values. The server does not load .env automatically. Without AGENTS_CONFIG, it loads the generic example: its placeholder routes must be replaced before inference. TECHNICAL_AGENTS_CONFIG is an optional explicit second agent file.

For multiple backends, copy config/providers.example.yaml, keep the profiles you use, and set MULTIAGENTS_PROVIDERS_CONFIG to your private copy. Set each agent's provider. Legacy NINEROUTER_URL and NINEROUTER_KEY remain supported. See provider configuration.

Examples

Ask your MCP client to:

“List the configured agents, route this architecture review to an appropriate agent, and submit it as an asynchronous job. Show its progress and final findings.”

“Create a workflow with diagnosis, implementation proposal, and review steps. Require concrete evidence before accepting each step.”

“List this backend's combos and known CLI references. Plan a separate combo for this project using only permitted models. Keep existing routes unchanged.”

“Test these members of the existing combo individually. Report which respond, their latency, and any failures. Do not edit the combo.”

The client must translate these requests into the tools below. Agents receive the context supplied by the client; they do not automatically gain filesystem or shell access.

All 25 MCP tools

Combos without breaking another CLI

Management is disabled unless configured. A private policy specifies project IDs, model allowlists, write/test permissions, and per-call limits. Administrative credentials are explicitly configured separately from inference credentials.

Existing combos are external and protected unless ownership is established through this MCP's persisted records. Optional consumers entries read only declared JSON files and extract model/small_model references. Unreadable files are reported; missing references never prove the absence of consumers.

Updates create a new uniquely named version. The server never overwrites/deletes an existing combo, changes global routing settings, rewrites agent files, or switches another CLI's primary model. Use the new version explicitly with project_id and combo_id on a task or workflow step.

test_combo defaults to availability-v1. Optional text-v1, json-v1, and instructions-v1 suites check synthetic cases deterministically, with up to 64 output tokens per request, a 20-second request limit, and zero MCP retries/fallbacks. The instruction suite runs two cases per model. Model allowlists, allow_tests, and member-count limits apply to all suites. Private reports retain results per case; they do not guarantee general quality or trigger combo edits. Tests consume quota and may cost money. Backend alias/account fallback can still occur; tool-calling probes are deferred.

Full configuration and recovery details: project combos and probes.

Diagnostics, history, and shared limits

Use diagnose or node dist/index.js --diagnose for an offline configuration check; use inspect_state to inspect owner identity and reservations before recovery. Neither tool deletes locks, adopts jobs, or repeats calls. Loaded runtimes require an MCP reload after updates.

list_agent_tasks supports limit/offset. get_agent_task returns bounded content pages with next_content_offset, or status only with include_content:false. Original stored results remain recoverable. Terminal summaries avoid loading complete history at normal startup; old records remain compatible without bulk rewriting.

Tools declare output schemas. Synchronous delegation sends progress when the client supplies progressToken; asynchronous jobs remain accessible by polling. Optional private provider limits reserve concurrency, requests, and conservative token units across cooperating processes. Input/output/response caps reject oversized operations explicitly. Reservations are not exact usage or monetary guarantees; uncertain execution keeps its reservation pending inspection.

See configuration and operational limits. Private-state behavior is validated on Linux/WSL; native Windows ACL privacy and complete macOS lifecycle behavior are not certified. Native Tasks remain an experimental protocol test, without production migration.

Execution and security boundaries

The local client supplies source/context, applies patches, executes commands, and checks real results. Delegated models produce proposals. Workflow approval does not grant operating-system permissions or execute a proposed command.

Combo tools are a separate, narrow administrative capability: configured management requests can create new combos, while test_combo can consume inference quota. No arbitrary shell or backend-database editor is provided.

Catalog access is not proof of successful inference, model quality, subscription access, or price. Generic Chat Completions compatibility does not imply native Anthropic/Gemini/Responses support or administrative API support. State may contain private prompts and evidence; keep it outside public repositories. This server assumes a trusted local MCP client, not multi-tenant isolation.

See security, workflow details, and the security assessment.

Development and packaging

npm test
npm run release:prepare
npm pack --dry-run --ignore-scripts

Release preparation stages an explicit allowlist for review; it does not publish. Private agents, credentials, jobs, workflows, combo plans, snapshots, and runtime data stay out of the public package.

The manual npm release workflow is prepared for tagged, CI-approved publication of the exact tested tarball with OIDC/provenance. An operator must first configure the external trusted publisher and protected GitHub environment; this checkout does not imply a completed live publication. Features described here reflect source changes and may precede the installed npm release.

Related MCP server: Jules AI MCP Server

Português brasileiro

Para que serve?

O MULTIAGENTS-MCP permite que seu cliente MCP trabalhe com uma equipe de agentes configurada por você, mantendo tarefas persistentes, fluxos com revisão e combos de modelos por projeto.

Você pode distribuir diagnóstico, proposta de implementação e revisão entre agentes diferentes; acompanhar trabalhos longos; exigir evidências antes de avançar; e escolher modelos de backends distintos sem trocar o modelo principal do seu assistente.

Os nomes, papéis, modelos, provedores, fallbacks e permissões são seus. Não há dependência de perfis pessoais do autor.

A gestão de combos e os testes individuais exigem a versão 0.5.0 ou superior. Configurações anteriores de inferência continuam compatíveis.

Funcionalidades

Como começar

1. Instale Node.js >=20.11. Use a configuração com npx mostrada na instalação pelo npm ou clone o repositório e execute npm ci e npm run build.

2. Copie config/agents.example.yaml para um arquivo privado, troque os placeholders por IDs reais e defina seus agentes.

3. Configure o cliente MCP com node, o caminho absoluto de dist/index.js e as variáveis mostradas na configuração em inglês.

4. Defina diretórios privados para jobs, workflows e combos. O servidor não carrega .env automaticamente.

5. Para vários backends, configure MULTIAGENTS_PROVIDERS_CONFIG e associe cada agente ao seu provider.

Na instalação pelo npm, use npx como comando do cliente; na instalação pelo código-fonte, use node com o caminho de dist/index.js. Recarregue a conexão MCP depois de alterar a configuração.

Nenhum nome de agente é obrigatório. Há especializações de desenvolvimento, arquitetura, documentação, tradução e filologia, mas você escolhe quais utilizar. O agente recebe os trechos fornecidos pelo cliente; não ganha acesso automático ao seu computador.

Exemplos de uso

“Peça um diagnóstico a um agente e uma revisão independente a outro. Mostre as divergências antes de propor alterações.”

“Organize diagnóstico, proposta de correção e revisão em um workflow. Só avance quando houver evidências.”

“Veja os combos e as referências de outras CLIs. Planeje um combo separado para este projeto com meus modelos permitidos.”

“Teste individualmente os modelos deste combo e mostre quais responderam e quais falharam, sem modificá-lo.”

Ferramentas disponíveis

• Descoberta e diagnóstico: list_agents, list_providers, list_models, health_check, diagnose, inspect_state.

• Delegação e jobs: route_task, delegate_agent, submit_agent_task, submit_routed_task, get_agent_task, list_agent_tasks, cancel_agent_task, retry_agent_task.

• Workflows: create_workflow, get_workflow, advance_workflow, approve_workflow_action, record_workflow_action, review_workflow_step, replan_workflow.

• Combos e testes: list_combos, plan_combo, apply_combo_plan, test_combo.

Proteção de rotas e testes

A gestão exige habilitação explícita no arquivo privado. Você determina projetos, modelos autorizados e permissões de criação, atualização e teste. Credenciais administrativas são separadas das de inferência.

Combos externos são protegidos. A descoberta de consumidores lê apenas arquivos JSON declarados e extrai referências de modelo. Uma atualização cria outra versão com nome único: o combo anterior continua intacto, inclusive para consumidores desconhecidos. Nenhuma configuração de OpenCode ou outra CLI é reescrita.

Para usar uma versão nova, informe project_id e combo_id na tarefa ou etapa do workflow. Jobs revalidam a seleção antes de executar, inclusive em novas tentativas.

test_combo mantém availability-v1 como padrão e oferece as suítes opcionais text-v1, json-v1 e instructions-v1. Cada caso usa até 64 tokens e 20 segundos, sem fallback/repetição pelo MCP; a suíte de instruções tem dois casos por modelo. Permissões, allowlist e limite de modelos continuam obrigatórios. Relatórios privados mostram resultados determinísticos por caso, sem garantir qualidade geral ou modificar combos. Os testes consomem cota e podem gerar custos; o backend ainda pode resolver aliases ou trocar contas. Testes de ferramentas permanecem adiados.

Configuração, permissões e recuperação: combos e testes.

Diagnóstico, histórico e operação

Há 25 ferramentas. diagnose e --diagnose verificam a configuração offline; inspect_state inspeciona propriedade e reservas sem apagar locks ou repetir operações. Alterações de runtime/configuração exigem recarregar o MCP.

O histórico usa resumos leves e preserva os registros originais. Listagens aceitam limit/offset; conteúdo pode ser recuperado por páginas com next_content_offset, ou omitido com include_content:false. Ferramentas anunciam schemas de saída; progresso depende de progressToken fornecido pelo cliente e não substitui a consulta de jobs.

limits no provider habilita reservas compartilhadas opcionais. Processos precisam compartilhar configuração e diretório privado. Requisições, concorrência e unidades conservadoras de tokens são limitadas antes das tentativas; isso não representa custo monetário ou tokenização exata. Operações incertas exigem inspeção. Veja operação e recuperação.

Linux/WSL é o escopo confirmado para estado privado. Windows nativo/macOS não foram certificados integralmente. Tasks seguem como experimento de protocolo, e o workflow OIDC está preparado, dependendo de configuração externa e autorização do operador. Estas alterações de código não comprovam atualização do runtime instalado ou publicação no npm.

Limites importantes

O cliente controla os arquivos e comandos locais; os agentes produzem propostas. Aprovar uma ação no workflow não executa o comando nem concede permissões do sistema.

As ferramentas administrativas de combos executam somente as operações específicas autorizadas na política privada. Acesso ao catálogo não comprova inferência, assinatura, preço ou qualidade. Compatibilidade com Chat Completions não garante outros protocolos ou APIs administrativas.

Mantenha prompts, estado e credenciais fora de repositórios públicos. O servidor foi projetado para um cliente local confiável, não para isolamento entre usuários.

Provedores · Workflows · Combos · Segurança

License

MIT. See LICENSE.