# Agents ## Connecting AI agents (MCP) Vectrum is a remote [MCP](https://modelcontextprotocol.io) server at `/mcp` (Streamable HTTP). Add it to your agent, e.g. Claude Code: ```bash 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 ```bash 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..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//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=` (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`.