Developer guide

MCP server

brintOS ships a hosted Model Context Protocol server so AI agents — Cursor, Claude, or anything MCP-capable — can act on your account: participate fully in workspace chat, create and configure machines, manage issues and milestones, administer organizations, and more.

Endpoint

The server speaks stateless Streamable HTTP (JSON responses, no SSE stream):

https://brintos.io/api/mcp

Authorization is OAuth 2.1 with PKCE, exactly as the MCP authorization spec describes. You never create credentials by hand: the first time your agent connects it receives a 401 with discovery metadata, registers itself, and opens your browser to an approval page. Sign in, review the requested access, and click Authorize — the agent finishes the token exchange on its own.

Connecting from Cursor

Add the server to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):

{
	"mcpServers": {
		"brintos": {
			"url": "https://brintos.io/api/mcp"
		}
	}
}

Cursor detects the OAuth challenge and shows a "Needs login" prompt; approving it opens the brintOS consent page.

Connecting from Claude Code

claude mcp add --transport http brintos https://brintos.io/api/mcp

Then run /mcp inside Claude Code to complete the browser authorization.

What the agent can do

Tools run with the permissions of the account that approved access — the same rules as the web UI (repository permissions, organization roles, plan entitlements). Highlights:

Area	Tools
Workspace chat	Discover people, agents, and channels; create/update/archive channels; join/leave channels; manage channel members; start fresh DM, group-DM, and agent sessions; spawn and immediately run lineage-tracked child-agent tasks with `spawn_chat_child_conversation`; rename group/agent conversations; read/search/send/edit/delete messages and thread replies; manage reactions, pins, unread state, notification preferences, and mute settings; and upload/list/download chat images. Start with `search_chat_participants`, `list_chat_conversations`, or `list_chat_channels`. Mutations use the `_chat_` tools returned by `tools/list`.
Account	`get_authenticated_user`, `get_user`, `update_my_profile`, `set_user_follow`
Repositories	`list_my_repos`, `search_repos`, `get_repo`, `create_repo` (image machines or git repos, any visibility your plan allows), `fork_repo`, `update_repo` (rename, description, visibility, default branch, topics, feature toggles, archive), `delete_repo`, `list_branches`, `list_collaborators`, `add_collaborator`, `remove_collaborator`, `set_repo_star`, `set_repo_watch`
Issues	`list_issues`, `get_issue`, `create_issue`, `update_issue` (edit, close as completed / not planned, reopen, milestone), `add_issue_comment`, `update_issue_comment`, `delete_issue_comment`, `add_issue_labels`, `remove_issue_label`, `add_issue_assignee`, `remove_issue_assignee`
Labels & milestones	`list_labels`, `create_label`, `update_label`, `delete_label`, `list_milestones`, `create_milestone`, `update_milestone`, `delete_milestone`
Organizations	`list_my_orgs`, `get_org`, `create_org`, `update_org`, `list_org_members`, `invite_org_member`, `set_org_member_role`, `remove_org_member`
Pull requests	`list_pull_requests`, `get_pull_request`, `add_pull_request_comment`

Actions taken through MCP are first-class: chat messages and unread state appear immediately in the workspace, agent participants can reply, issue changes appear on the timeline, watchers get the same email notifications, and audit-relevant operations are attributed to your user. Destructive tools such as delete_chat_message, archive_chat_channel, and delete_repo require an explicit confirmation argument.

Site-admin tools

Accounts with site-admin access additionally see admin_* tools covering the support-ticket queue (list/stats/reply/triage, including internal notes), forum management (categories, pin/lock/move/delete), user administration, site metrics, the /admin/data entity browser, the audit log, and announcement sending. These tools are invisible to — and uncallable by — everyone else, and every admin mutation lands in the audit log.

Authorization details

Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server (RFC 9728 / RFC 8414).
Registration: open dynamic client registration at /oauth/register (RFC 7591). Public clients only; PKCE S256 is mandatory.
Consent: /oauth/authorize — always shown, always tied to your logged-in session.
Tokens: /oauth/token issues an 8-hour access token plus a rotating refresh token. Access tokens also work as Bearer credentials against the REST API (repo:read / repo:write scopes).
Revocation: Settings → Authorized applications revokes a client instantly; the minted tokens are also visible under Personal access tokens.

Calling the API directly

The endpoint is plain JSON-RPC 2.0 over POST, so you can drive it without an MCP SDK once you hold a token:

curl -s https://brintos.io/api/mcp \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
	     "params":{"name":"create_issue","arguments":{
	       "owner":"you","repo":"your-machine",
	       "title":"Found via MCP","body":"Hello from an agent."}}}'

One MCP connection acts as you. Only authorize clients you trust, and prefer a separate machine account for unattended automation.