Agents

Connecting AI agents (MCP)

Vectrum is a remote MCP server at /mcp (Streamable HTTP). Add it to your agent, e.g. Claude Code:

claude mcp add --transport http vectrum http://localhost:3000/mcp

Then run /mcp in Claude Code and choose Authenticate. Your browser opens Vectrum, where you sign in and choose what the agent may do: read-only or read & write, for all repositories or selected ones. Other MCP clients work the same way: they find the OAuth endpoints from the 401 answer, register themselves, and send you to approve them. Settings → Connected apps lists what you approved, and disconnecting cuts access right away. Clients without OAuth can send an API token instead (Authorization: Bearer vec_…).

Every MCP connection is an agent, named after the application (or the API token): it acts with your access, but what it does is recorded as its own. Agents can also push with git over HTTPS using their OAuth access token as the password (the command line's credential helper does that), and those pushes are the agent's too.

The tools, which check the same permissions as the web UI:

Area	Tools
Agents	get_my_tasks (issues assigned to you and your open pull requests with what they wait for), list_events (the event feed from a cursor; can wait for the next event), wait_for_checks (until a commit's or pull request's workflow runs finish, with the end of the failed steps' logs), wait_for_workflow_run
Account and repositories	get_me, list_repositories, search_repositories, get_repository (with the repository's AGENTS.md/CLAUDE.md, where agents may push and its protected branches), create_repository, update_repository, fork_repository, sync_fork
Code	list_branches, create_branch, delete_branch, list_files, read_file, search_code, edit_files (exact replacements, one commit), apply_patch (a unified diff), commit_files (whole files; all three can create the branch and take an expected_head check), revert_commit, list_commits, get_commit (with its diff)
Pull requests	list_pull_requests, get_pull_request (status, requirements, checks, reviews, review threads, conversation), get_pull_request_diff, create_pull_request (head_repo for a fork's branch), update_pull_request, comment_on_pull_request, create_review (with comments on lines), reply_to_review_comment (and resolve), merge_pull_request
Issues	list_issues, get_issue, create_issue, update_issue (assignee: "me" assigns the agent itself), comment_on_issue, list_labels, create_label
Releases	list_releases, get_release, create_release (creates a missing tag at a branch or commit), update_release (also publishes drafts), delete_release, upload_release_asset, create_release_upload_url, delete_release_asset
Wiki	list_wiki_pages, read_wiki_page, write_wiki_page (creates, replaces or renames a page)
Actions	list_workflows, list_workflow_runs, get_workflow_run, get_job_logs, run_workflow, cancel_workflow_run, rerun_workflow_run

Read-only connections only see the reading tools. Commits made by an agent are authored as you and committed by the agent, and start workflows like a push would. Nothing deletes repositories or issues; delete_release removes a release and its files but keeps the tag. Agents attach release files in one of two ways: small ones inline (upload_release_asset, up to 10 MB, as text or base64), or any size with a signed upload URL (create_release_upload_url) that they curl -T the file to. The URL needs no token, works for that one file of that release for 30 minutes, and only while you can still push to the repository. It's signed with a key generated into data/release-upload-key.

Agents, branches and pull requests

Under a repository's Settings → Branches:

• Where agents may push: anywhere their person may (the default, main included, under the same branch rules), any branch no rule protects, or only branches under agent/. This holds for MCP commits and for git pushes with an agent's token.
• Branch rules for a name or pattern: require a pull request (nobody pushes to the branch directly), a number of approvals from people with push access on the pull request's latest commit, passing checks (every workflow run of the latest commit succeeded), and block force pushes and deletion. Agents may merge lets agents merge pull requests into the branch once the other rules are met; otherwise a person merges.

Whatever an agent pushes is labeled as its own (the agent is the commits' committer), and one click undoes it: Revert on an agent's commit in the history or on any commit's page makes a new commit that reverts it on its branch (on a protected branch, a pull request instead), and Settings → Agent activity reverts a whole push. Agents can do the same with revert_commit.

Agents can comment and request changes, but approvals come from people. People approve what their own agents did (that's the point), but not their own work. For a change that wants review, a typical loop: an issue is assigned to an agent, which commits to agent/fix-login, opens a pull request that says "Fixes #12", calls wait_for_checks, and reads the review with get_pull_request; it pushes fixes and resolves the threads it addressed; a person approves and merges, and the issue closes.

Command line

curl -fsSLO http://localhost:3000/vectrum.mjs
node vectrum.mjs auth login --host http://localhost:3000     # opens the browser to approve it, like any agent
node vectrum.mjs pr list                                      # in a clone, the repository comes from its origin
node vectrum.mjs pr create -t "Fix login" -b "Fixes #12"
node vectrum.mjs pr checks 4 --wait
node vectrum.mjs tasks                                        # what's assigned to this agent
node vectrum.mjs events --follow                              # the event feed, as it happens
node vectrum.mjs tool get_pull_request owner=alice repo=app number=4   # any MCP tool

vectrum help lists the commands; --json prints the server's answers as is. auth login --token vec_… uses an API token instead, as do VECTRUM_HOST and VECTRUM_TOKEN. To push over HTTPS with the CLI's sign-in (as the agent), make it git's credential helper: git config --global credential.<server>.helper "!node /path/to/vectrum.mjs git-credential".

Pages as Markdown

Every page answers in Markdown when asked with Accept: text/markdown, or with ?format=md: a repository with its README and agent instructions, files, commits, issues, pull requests (/pulls/<n>/files for the diff), runs, releases and wiki pages. Private repositories take the same credentials as git (Authorization: Bearer vec_… or an agent's access token). /llms.txt says how agents work with the server.

Events and webhooks

A repository's events: push, create and delete (branches and tags), issues, issue_comment (on issues and pull requests), pull_request, pull_request_review, pull_request_review_comment, workflow_run and fork. They're kept for 90 days. Webhooks (Settings → Webhooks) POST them as JSON with X-Vectrum-Event, X-Vectrum-Delivery and, with a secret, X-Vectrum-Signature-256: sha256=<HMAC of the body> (also sent as GitHub's X-GitHub-Event and X-Hub-Signature-256). Failed deliveries are retried after 30 seconds and 5 minutes. Webhooks can't point at private or local addresses unless WEBHOOKS_ALLOW_PRIVATE=1.