Biro MCP Server

Model Context Protocol server for Biro.

This package is a thin MCP wrapper over the existing Biro REST API. It does not talk to the database directly and it does not reimplement business logic.

Authentication

The server reads its configuration from environment variables:

• BIRO_API_URL - Biro base URL, for example http://localhost:3100
• BIRO_API_KEY - bearer token used for /api requests
• BIRO_COMPANY_ID - optional default company for company-scoped tools
• BIRO_AGENT_ID - optional default agent for checkout helpers
• BIRO_RUN_ID - optional run id forwarded on mutating requests

Usage

npx -y @biroai/mcp-server

Or locally in this repo:

pnpm --filter @biroai/mcp-server build
node packages/mcp-server/dist/stdio.js

Tool Surface

Read tools:

• biroMe
• biroInboxLite
• biroListAgents
• biroGetAgent
• biroListIssues
• biroGetIssue
• biroGetHeartbeatContext
• biroListComments
• biroGetComment
• biroListIssueApprovals
• biroListDocuments
• biroGetDocument
• biroListDocumentRevisions
• biroListProjects
• biroGetProject
• biroGetIssueWorkspaceRuntime
• biroWaitForIssueWorkspaceService
• biroListGoals
• biroGetGoal
• biroListApprovals
• biroGetApproval
• biroGetApprovalIssues
• biroListApprovalComments

Write tools:

• biroCreateIssue
• biroUpdateIssue
• biroCheckoutIssue
• biroReleaseIssue
• biroAddComment
• biroSuggestTasks
• biroAskUserQuestions
• biroRequestConfirmation
• biroUpsertIssueDocument
• biroRestoreIssueDocumentRevision
• biroControlIssueWorkspaceServices
• biroCreateApproval
• biroLinkIssueApproval
• biroUnlinkIssueApproval
• biroApprovalDecision
• biroAddApprovalComment

Escape hatch:

• biroApiRequest

biroApiRequest is limited to paths under /api and JSON bodies. It is meant for endpoints that do not yet have a dedicated MCP tool.

Biro Control Tools (stubs — pending P1.x wiring)

These tools define the agent participation surface for in-context Biro agents. Handlers currently throw NotImplementedError; HTTP wiring will land once the event bus (P1.1) is available.

• claim_task — atomically claim an issue as the current agent
• report_progress — post a progress comment visible to operators
• request_budget_increase — request operator-approved budget increase
• query_teammates — list @-mentionable agents in the company, optionally filtered by role
• read_org_chart — get the org chart with goals and reporting lines (read-only)
• check_governance — check whether a planned action is permitted by governance rules (read-only)