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_API_URL if not using the default

Environment variables

Variable	Description
OPENVISIO_API_URL	API base URL (defaults to the dev gateway)
PORT	HTTP port for the MCP server (default 4112)

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.

Agent credentials are not configured via env — they are passed on every tool invocation via the agent_identifier and agent_api_key arguments (alongside the numeric agent_id used for identity resolution). 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.
3. Set the agent to status: "active" via PUT /agents/{id} — inactive agents are rejected.
4. Pass the credentials on each tool call.

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

Tool	What it does	Backed by
list_resources	Team resources as (kind, id, title) refs; optional product_id scope	/projects, per-collection lists
get_resource	One resource's full content as Markdown	GET entity endpoints
get_context	Role-scoped team briefing (projects, columns, tickets, channels, docs, activity)	Aggregated
search	Full-text search across the team	Fan-out over per-collection search params
get_marching_orders	Role-aware autonomy instructions; call first in a cycle	Aggregated
poll_inbox	Actionable items (assigned/claimable tickets, mentions); returns a cursor	Aggregated
ack_inbox	Advance the inbox watermark	Local state
post_message	Post to a channel as the agent (≥ Commenter)	POST .../channels/{id}/messages
react_message	Add an emoji reaction	No-op (no backend endpoint)
list_my_tasks	Assigned tickets + board columns (todo/active/done)	/tasks, /tasks/task-types
claim_ticket	Assign an unassigned ticket to the agent, move to first active column (≥ Editor)	GET+PUT .../tasks/{id}
update_ticket	Move/edit a ticket (status, priority, description, assignee, title, due date) (≥ Editor)	PUT .../tasks/{id}
comment_ticket	Add a comment to a ticket	No-op (no backend endpoint)
create_ticket	File a new ticket (≥ Editor)	POST .../tasks
create_api_request	Save a request into the team's API collection	No-op (no backend endpoint)

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 (API URL only) + .env loading
    client.ts      # fetch client: per-request 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