MULTIAGENTS-MCP

A local MCP server for delegating tasks to agents configured by each user, backed by OpenAI-compatible Chat Completions endpoints. Supports synchronous tasks, persistent asynchronous jobs, and reviewed workflows.

The server does not include the author's personal agents, models, combos, or credentials. Agent IDs, model routes, providers, fallbacks, and specializations belong to your configuration. The MCP does not create model aliases or change your MCP client's primary model.

Install and configure

Requires Node.js >=20.11.

npm install
npm run build
cp config/agents.example.yaml /absolute/path/to/private/agents.yaml

Edit the copied YAML. Replace every your-model-id with an actual model or alias available in your backend. Rename, remove, or add agents as needed. The included developer, reviewer, and assistant are examples, not required agent IDs or preconfigured models.

agents:
  my-agent:
    route: model-id-from-your-backend
    role: my-specialization
    task_kinds: [development, documentation]
    description: Produces proposals from the context supplied by the client.
    route_strategy: fallback

Optional task_kinds: development, architecture, documentation, translation, philology. Automatic routing uses these declarations; if none matches, it uses the first configured agent. An explicit agent field or leading @my-agent selects an existing ID. Unknown IDs are rejected. Complex tasks suggest review/implementation/review only when both specializations exist.

Configure your MCP client with absolute paths:

[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"

Store real credentials only in private configuration. The server does not load .env automatically. Without AGENTS_CONFIG, it loads the generic example; its placeholder routes must be configured before inference. It never searches for a second agent file implicitly. TECHNICAL_AGENTS_CONFIG remains an optional explicit second file for existing installations.

For multiple backends, copy config/providers.example.yaml, keep only profiles you use, supply their credential environment variables, and set MULTIAGENTS_PROVIDERS_CONFIG. Assign a provider to each agent. See providers. Legacy NINEROUTER_URL and NINEROUTER_KEY remain supported.

Related MCP server: worker-bridge

Tools and execution

• list_agents, list_providers: inspect configured agents and backend profiles.

• health_check: check a backend catalog or explicitly request an inference probe.

• delegate_agent: wait for a short task.

• submit_agent_task, get_agent_task, list_agent_tasks: submit and inspect persistent jobs.

• route_task, submit_routed_task: select configured agents using task signals.

• Workflow tools: plan steps, review evidence, approve proposals, and record actual client execution.

The MCP produces proposals. The client supplies relevant source/context, applies changes, executes tools, and records actual results. Model proposals and approvals never grant operating-system permissions. See workflows and security.

Validation and publication

npm test
npm run release:prepare

Release preparation stages an explicit allowlist for review. Personal config/agents.yaml, config/technical-agents.yaml, editorial job inputs, runtime state, and local model-selection notes are excluded from Git/package publication. Keep private files outside the repository when possible. Preparing a release does not publish it.

Português

O MULTIAGENTS-MCP é um servidor MCP local para delegação de tarefas a agentes definidos por cada usuário. Conecte seu próprio backend compatível com OpenAI Chat Completions e configure seus modelos, aliases, papéis e fallbacks.

Copie config/agents.example.yaml para um arquivo privado, substitua your-model-id por IDs reais do seu backend e defina AGENTS_CONFIG no cliente MCP. Os nomes dos agentes são livres. task_kinds declara as especializações usadas pelo roteamento; @id ou o campo agent seleciona um agente configurado.

Não são distribuídos os perfis pessoais do autor. O MCP não cria combos, não exige agentes de tradução/revisão e não altera o modelo principal do cliente. Configurações pessoais existentes continuam locais e devem ser apontadas explicitamente.

O cliente controla arquivos e comandos; o servidor produz análises e propostas. Catálogo acessível não comprova inferência: use health_check em modo inference para uma verificação real, considerando o custo do seu backend.