@aiosbrain/mcp
Read-only access to an AIOS Team Brain from an MCP host. Requires Node.js 22 or newer; no AIOS checkout, global toolkit installation, native modules or runtime dependencies.
Start with npx -y @aiosbrain/[email protected]. Configure AIOS_BRAIN_URL and AIOS_API_KEY,
or use the owner-only default tuple in ~/.aios/credentials.json:
{
"version": 1,
"default": {
"brain_url": "https://brain.example.com",
"api_key": "<your API key>"
}
}
Keep this file private (chmod 600 on POSIX; owner-only ACL on Windows). Host
configuration should contain the version-pinned command, never the API key. The host
installer is tracked separately in AIO-1112; do not assume it is available in your toolkit.
Environment credentials take precedence. Existing .env and aios.yaml configuration
remains supported. Stored credentials are tied to their Brain origin: changing the URL
alone cannot send a stored key to another server. An environment key needs an explicit
or existing workspace URL; it never borrows a URL from the global credential file.
Startup performs one /api/v1/me probe with a three-second deadline. Team members get
all nine Brain tools; external members get the five brain tools. Missing configuration,
revoked credentials, delegated tokens, malformed identity responses and network failures
register no Brain tools and produce a diagnostic on stderr. Availability stays fixed until
restart; the Brain checks authorization on every call, including after membership changes.
| Toolset | Tools |
|---|---|
brain | brain_status, brain_search_evidence, brain_query, brain_pull_items, brain_get_item |
board | brain_list_projects, brain_list_tasks, brain_list_decisions, brain_stakeholders |
--toolsets brain,board overrides AIOS_MCP_TOOLSETS. Repeated --tools <name> adds tools;
explicit selections form a union and then intersect with the permitted surface. all selects
all permitted tools. The workspace collector is available only in the toolkit's aios mcp.
Transport is newline-delimited stdio, with serialized JSON-RPC responses on stdout and
all diagnostics on stderr. Initialize returns protocol 2025-11-25 and this package's
version. Query answers preserve citation markers and source lists. This package does not
provide a remote HTTP endpoint or write tools.
Maintainers: generate and pack from the committed candidate with
node packages/mcp-build/pack.mjs --out <new-artifact-directory> in the source repository.
Publish the accepted tarball, never the unbuilt source directory.
Evidence-first answers
brain_search_evidence (Brain API 1.27+) returns ranked source passages, citations, dates and recorded contributor roles without calling an answering model. The host composes the answer and can expand sources with brain_get_item. It belongs to the read-only brain toolset. Arguments: query, optional project, optional limit (default 8, max20). Responses remain valid JSON under 20,000 characters; truncation is disclosed. Older servers report upgrade required, and HTTP failures are never converted to no matches. No additional key or hosted MCP service is required.
0.2.1
Explicit integer evidence-search limits now pass MCP argument validation. The packed artifact acceptance test covers an explicit limit of 10 as well as live retrieval.