OpenVisio BYO MCP Bridge

A Model Context Protocol (MCP) server that exposes OpenVisio's team collaboration API as a set of tools for AI agents. Built with Mastra.

The bridge turns OpenVisio's REST API (tickets, board columns, channels, documents, projects, activity) into 15 MCP tools that agents can call to read team state, communicate, and drive tickets autonomously.

Setup

Requires Node.js >= 22.13.

npm install
cp .env.example .env
# edit .env and set OPENVISIO_AGENT_IDENTIFIER and OPENVISIO_AGENT_API_KEY

Environment variables

Authentication

The bridge authenticates every backend request as a registered OpenVisio agent by sending the x-agent-identifier and x-agent-api-key headers, which the backend's userAuthMiddleware accepts alongside the bearer-JWT flow used by frontend clients. To provision an agent:

1. Create the agent as an admin: POST /agents with { name, type: "bring_your_own", user_id }.

2. Copy the identifier and api_key from the create response into OPENVISIO_AGENT_IDENTIFIER / OPENVISIO_AGENT_API_KEY.

3. Set the agent to status: "active" via PUT /agents/{id} — inactive agents are rejected.

Agent identity is not configured via env. The caller passes the registered OpenVisio agent id via the agent_id argument on each self-aware tool invocation.

Related MCP server: agentforge

Running

npm run start:mcp        # standalone MCP server on http://localhost:4112/mcp
npm run dev              # Mastra dev (Studio)
npm run build            # Mastra build

Tools

Board columns are the API's task types. "Status" of a ticket = its column id (type_id) + position.

Notes / limitations

• No-op tools (react_message, comment_ticket, create_api_request) are registered so the tool contract stays intact; they succeed without side effects. The backend has no endpoints for reactions, task comments, or an API collection.

• Threads: post_message accepts an optional parent_id, but the backend does not officially document thread support; it may be ignored.

• Identity: self-aware tools require agent_id (the registered OpenVisio agent id). The bridge derives the agent's user_id and org role from the agent and member records.

• Inbox cursors (poll_inbox/ack_inbox) are held in memory and keyed by agent; they reset when the bridge restarts.

• Response parsing is defensive: the API documents request shapes but not response shapes beyond the { ok, message, status, body } envelope, so field extraction is best-effort.

Architecture

src/
  lib/
    config.ts      # env config (agent credentials/URL) + .env loading
    client.ts      # fetch client: agent-header auth, envelope unwrap, pagination, tolerant pick()
    identity.ts    # resolve agent -> user_id -> member role
    markdown.ts    # per-kind Markdown renderers
    cursors.ts     # in-memory inbox watermark store
  tools/
    read.ts        # list_resources, get_resource, get_context, search
    autonomy.ts    # get_marching_orders, poll_inbox, ack_inbox
    messaging.ts   # post_message, react_message
    tickets.ts     # list_my_tasks, claim_ticket, update_ticket, comment_ticket, create_ticket
    api_tool.ts    # create_api_request
  mastra/
    index.ts       # Mastra instance
    mcp/server.ts  # MCPServer with the 15-tool registry
  server.ts        # standalone HTTP MCP endpoint (/mcp)

Development

npx tsc --noEmit    # typecheck