noeva-agents-mcp

MCP server that lets external LLMs invoke NOEVA Mastra agents and converse with them. Protocol adapter over the noeva-agents server (default https://agents.noeva.ai): the chat SSE stream is consumed server-side and collapsed into a flat envelope, so MCP clients never deal with streaming.

Public install (npm)

Installazione pubblica senza credenziali GitHub:

npx -y @noeva/agents-mcp

Config MCP (es. Claude Desktop):

{
  "mcpServers": {
    "noeva-agents": {
      "command": "npx",
      "args": ["-y", "@noeva/agents-mcp"],
      "env": {
        "NOEVA_AGENTS_BASE_URL": "https://agents.noeva.ai",
        "NOEVA_API_KEY": "noeva_sk_..."
      }
    }
  }
}

Il canale @my-ginkgo/noeva-agents-mcp su GitHub Packages resta disponibile per uso interno (richiede un PAT read:packages).

Tools

| Tool | Actions | What it does | | ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | agents_catalog | list [read] | Curated whitelist of invocable agents (id, title, description, example). Static — no upstream call. | | agents_chat | ask [soft-write] | One conversational turn with a whitelisted agent. Returns { text, tool_calls, thread_id, usage, citations }; a tool_calls entry carries an error field when that tool invocation failed mid-turn. | | agents_threads | list [read] | Paginated thread listing for a resource_id (by convention, the agent id). |

The conversational loop

1. agents_chat action=ask with workspace_id, agent_id (pick from agents_catalog; noevaSuperAgent is the default recommendation) and message. Omit thread_id.
2. The envelope comes back with a generated thread_id (mcp-<uuid>).
3. Follow-ups: call ask again with the SAME thread_id — the agent keeps its memory of the conversation.
4. If a turn times out, the server keeps generating in the background (stream recovery): retry ask on the same thread_id to retrieve the result.

Environment variables

| Variable | Default | Notes | | ------------------------- | ------------------------- | --------------------------------------------------------------------------------------- | | NOEVA_API_KEY | — (required, stdio) | Personal NOEVA API key (noeva_sk_…), generated in the Noeva app (Profile → API Keys). | | NOEVA_AGENTS_BASE_URL | https://agents.noeva.ai | The noeva-agents server. Plain http allowed only for loopback. | | NOEVA_AGENTS_TIMEOUT_MS | 120000 | Whole-turn budget for the chat stream. | | MCP_RATE_LIMIT_PER_MIN | 60 | Courtesy in-process limiter (not a security control). | | LOG_LEVEL | info | pino level; stdio logs go to stderr. |

Every call also needs a workspace_id argument (the API key is user-scoped, not workspace-scoped) — find yours in the Noeva app or via the noeva-core MCP.

Claude Desktop

{
  "mcpServers": {
    "noeva-agents": {
      "command": "npx",
      "args": ["-y", "@my-ginkgo/noeva-agents-mcp"],
      "env": {
        "NOEVA_API_KEY": "noeva_sk_…",
        "NOEVA_AGENTS_BASE_URL": "https://agents.noeva.ai"
      }
    }
  }
}

Development

pnpm install        # needs GitHub Packages auth for @my-ginkgo scope
pnpm test           # vitest (unit + integration)
pnpm run typecheck
pnpm run lint
pnpm run inspect    # MCP Inspector against src/stdio.ts

HTTP build (central deploy): pnpm run start:http — stateless StreamableHTTP on POST /mcp, bearer-gated, per-request auth forwarded to noeva-agents.