Reference

Vector documentation

This page documents the workspace data model, first-party CLI API, MCP server, context bundles, and permission rules used by Vector. It also covers the workspace product surface: worklists, planning, docs, canvases, templates, Feed, Insights, developer access, billing, imports, exports, and GitHub. It is written for engineers, operators, and agent implementers who need exact contracts.

Reference modecontract firstTables describe request shape, required scopes, returned data, and failure behavior. Operational routing details live in internal operations docs. Agents should start with /llms.txt.

Sign in to the workspace in the browser. The browser is where a human creates and revokes programmatic access.
Use the workspace console for worklists, saved views, projects, sprints, initiatives, docs, canvases, templates, Feed, Insights, admin, and billing.
Open Developer access. Use Tokens for human-owned terminal scripts and Agents for MCP-enabled coding agents.
Copy the token immediately. Vector shows programmatic tokens once and stores only a hash after creation.
In your terminal, export the token and call GET /cli/v1/me before any write. Confirm actor, scopes, and workspaceId.
For agent work, start the agent from a local terminal with the MCP credential configured. The agent should not scrape the browser UI.
Use North Graph before and after local code changes when an agent needs codebase facts, risk analysis, impacted tests, or verification evidence.

Quickstart

Humans and agents start differently.

Humans should use the browser for setup and review. Agents should use the documented contracts from a terminal, verify credentials first, and preserve structured outputs for audit and debugging.

Human quickstart

Open the workspace in the browser.
Use the UI for worklists, planning, docs, canvases, workspace setup, teams, private-team visibility, token creation, revocation, and human review.
Create a CLI token only when you need terminal automation or CI-style scripts.
Create an agent identity only when a terminal agent needs MCP access.
Keep token values out of screenshots, prompts, issue comments, and shell history.

Agent quickstart

Read /llms.txt first. It points to the public docs, agent contracts, CLI endpoint rules, schemas, and security boundaries.
Decide the surface before acting: hosted Vector MCP for workspace records, local North Graph MCP for repo facts, CLI for scripts.
Verify credentials with /cli/v1/me or MCP initialize before reading or writing data.
Use tools/list before tool calls. Missing tools mean the agent is not allowed to use them.
Read a context bundle before planning implementation work.
Use idempotency keys for mutating retries and preserve requestId values in logs or comments.

Placeholder	Replace it with
`VECTOR_BASE_URL`	The web app origin, for example https://app.example.com.
`VECTOR_TOKEN`	A CLI token created from Developer access -> Tokens.
`VECTOR_MCP_TOKEN`	An MCP agent credential created from Developer access -> Agents.
`workspaceId`	The workspace ID returned by /cli/v1/me, not a guessed slug.

Install and setup

Each surface has a different setup path.

The CLI HTTP API only needs a token and an HTTP client. North Graph is part of the local Vector CLI. Hosted Vector MCP is configured as an HTTP MCP server. North Graph MCP is started locally by the Vector CLI.

Surface	Install	Credential	Verify
Workspace UI	No local install. Open the Vector web app and sign in.	Signed browser session.	Create or open the workspace, then use Developer access to create tokens.
CLI HTTP API	No SDK install required. Use curl, fetch, or any HTTP client against /cli/v1.	CLI token from Developer access -> Tokens.	Call GET /cli/v1/me and confirm actor, scopes, and workspaceId.
Vector CLI for North Graph	The CLI package is in this repo today. Build it locally or run its pnpm script until a public package is published.	No Vector token is required for local repo analysis.	Run vector north doctor --json from a repository root.
Hosted Vector MCP	No local server install. Configure an MCP-capable client to call the Vector /mcp endpoint over HTTP.	MCP agent credential from Developer access -> Agents.	Run initialize, then tools/list, and confirm only allowed tools are listed.
North Graph MCP	Uses the local Vector CLI. Start it with vector north mcp from the repository root.	No hosted Vector token is required for local repo facts.	Connect the terminal agent to the local MCP server and run tools/list.

CLI API

Use /cli/v1 from any terminal

# CLI HTTP API: no SDK install required.
export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_TOKEN="vta_..."

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/me"

North Graph CLI

Run North Graph locally

# Current repo-local Vector CLI path.
pnpm install
pnpm --filter @vector/cli build
pnpm --filter @vector/cli vector -- north doctor --json

# Once the vector binary is on PATH:
vector north doctor --json

MCP clients

Configure hosted Vector and local North Graph separately

{
  "mcpServers": {
    "vector": {
      "transport": "http",
      "url": "${VECTOR_BASE_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${VECTOR_MCP_TOKEN}"
      }
    },
    "north-graph": {
      "command": "vector",
      "args": ["north", "mcp"]
    }
  }
}

Choose surface

CLI, hosted MCP, and North Graph are separate surfaces.

The CLI HTTP API is for workspace JSON over /cli/v1. Hosted Vector MCP is for agent access to workspace tools. North Graph is local repo intelligence inside the Vector CLI, and its local MCP server is started with vector north mcp.

Choose	Use when	Avoid
Browser UI	A human is using worklists, saved views, planning, docs, canvases, templates, Feed, Insights, admin, billing, private visibility, tokens, or reviewing agent output.	Do not ask an agent to scrape the UI when a CLI or MCP contract exists.
CLI /cli/v1	A script, CI job, or terminal command needs JSON access to workspaces, teams, issues, comments, context bundles, or linked development metadata.	Do not use CLI tokens as device sessions or broad public API keys.
Hosted Vector MCP	A terminal agent needs permission-filtered workspace context, linked artifact metadata, or needs to create, update, comment, or request approval on work.	Do not use hosted Vector MCP for local repository indexing or source-code analysis.
North Graph CLI or local MCP	A terminal agent needs repository symbols, callers, effects, policies, diff risk, impacted tests, or verification reports.	Do not treat North Graph output as permission to bypass Vector, GitHub, CI, review, or human approval.

Surface	Runs through	Use when	Credential	Data
CLI HTTP API	/cli/v1 over HTTPS.	Any terminal script, curl command, CI job, or future packaged Vector CLI that needs workspace JSON.	CLI token.	Workspace work data: identity, workspaces, teams, issues, comments, context, and linked GitHub metadata.
Hosted Vector MCP	/mcp over HTTPS.	Terminal agents that understand MCP and need permission-filtered Vector workspace context or safe work mutations.	MCP agent credential.	Workspace work tools: search_work, create_issue, update_issue, add_comment, read_context_bundle, request_approval.
North Graph CLI	Local command: vector north ...	Humans or scripts that need local codebase facts, policy checks, diff risk, impacted tests, or verification reports.	Local repository access.	Repo facts only. It is part of the Vector CLI, but it is not /cli/v1.
North Graph MCP	Local command: vector north mcp.	Terminal agents that need MCP access to local repo intelligence.	Local repository access.	Same local North Graph facts exposed through MCP. It is started by the CLI and is separate from hosted Vector MCP.

Prerequisites

What must exist before production use.

A production integration should begin with explicit workspace access, stable team boundaries, a known base URL, scoped credentials, and a local repository policy when code analysis is involved.

Requirement	Human check	Technical check
Workspace access	You can sign in, open the target workspace, and see the teams/issues you expect.	Programmatic calls only work after the human owner has active workspace membership.
Team model	Public and private teams are created before importing sensitive work.	Private-team filtering applies to UI, CLI, MCP, search, exports, notifications, and context bundles.
Base URL	You know the web app origin used by the workspace.	Use it as VECTOR_BASE_URL. Hosted MCP is served from the same origin at /mcp.
Credentials	A human creates either a CLI token or an MCP agent credential from Developer access.	Tokens are shown once, stored hashed, workspace scoped, and revocable.
Workspace knowledge	Docs, canvases, collections, and artifact links live in the target workspace before agents depend on them.	Use the workspace UI for full docs and canvas editing. CLI/MCP expose the stabilized context subset.
Plan and export expectations	The workspace plan supports the features the rollout will use, such as private teams, exports, Asks, SLAs, or Insights.	Plan-gated failures return stable 402 errors with plan_limit_exceeded or plan_upgrade_required.
Local repo	North Graph is run from the repository root when local codebase intelligence is needed.	Use vector.north.json for policy and vector north commands for local reports.

Production checklist

Use this checklist before trusting a script or agent.

The goal is not only to make the call succeed. The goal is to make it repeatable, auditable, permission-correct, and easy to debug after the fact.

Moment	Required action
Before first script	Create a least-privilege token, store it outside source control, call /cli/v1/me, and record the workspaceId.
Before first agent run	Create an agent identity, restrict allowed teams/tools, initialize hosted Vector MCP, run tools/list, then read a context bundle.
Before local code edits	Run North Graph index/diff inspection, identify risky effects, and list impacted tests.
Before relying on docs or canvas	Link the document or canvas to the relevant issue, project, or initiative and confirm the latest version was loaded.
Before using a saved worklist	Confirm the saved view visibility, filters, grouping, sorting, and count/facet behavior from the canonical worklist route.
Before a mutating retry	Use an idempotency key and retry only the exact same request body.
Before sharing evidence	Remove secrets, local paths, and source snippets unless a human explicitly approved sharing them.
Before closing work	Attach request IDs, command outputs, North Graph report summary, and verification results to the issue or handoff.

Token lifecycle

Create, verify, rotate, and revoke credentials deliberately.

A production-ready setup treats tokens as operational credentials with ownership, storage, verification, rotation, and revocation. Do not leave token management as tribal knowledge.

Stage	What to do	Production note
Create	Use Developer access -> Tokens for CLI or Developer access -> Agents for MCP credentials.	Creation is audited. Token value is shown once.
Store	Use a shell secret, CI secret store, password manager, or agent-local config.	Never commit tokens, paste them into prompts, or store them in issue comments.
Verify	Call /cli/v1/me for CLI tokens or MCP initialize/tools/list for agent credentials.	Confirm actor type, workspace, scopes, allowed tools, and visible teams.
Use	Send Authorization: Bearer <token> on every CLI/MCP request.	Every request still checks workspace membership, private teams, scopes, and object permissions.
Rotate	Create a replacement token, update the script/agent config, verify, then revoke the old token.	Do not edit existing leaked credentials in place.
Revoke	Use Developer access to revoke tokens or agent identities.	Revoked credentials should fail immediately or within the documented propagation window.

Token setup

Create programmatic access from the workspace, then use it from the terminal.

Humans sign in with the browser. Programs authenticate with a token created by an authorized workspace member. Tokens are scoped, revocable, shown once, and checked against workspace and private-team permissions on every request.

Credential	Plain English use	Technical shape	Where to create it	What to copy
CLI token	Use this when a human runs terminal scripts or a future packaged Vector CLI.	kind=cli, principalType=user, workspace-scoped, revocable, hashed at rest.	Workspace console -> Developer access -> Tokens -> Create token	The generated token value. It is shown once.
MCP agent credential	Use this when Codex, Claude Code, Cursor, Windsurf, or another terminal agent needs Vector context.	kind=mcp, principalType=agent, owner user required, allowedTeamIds and allowedTools enforced.	Workspace console -> Developer access -> Agents -> Create agent	The generated MCP token plus the allowed teams and tools.

Important

A token is a password for a program. Copy it once, keep it out of prompts and logs, store it in a terminal environment or secret store, and revoke it when the script or agent no longer needs it.

Check	Expected result
CLI token creation	The UI shows one token value once. After dismissal, only name, prefix, kind, last-used time, and revoke action remain.
GET /cli/v1/me	Response includes requestId, actor.actorType, token.scopes, token.workspaceId, and accessible workspaces.
MCP initialize	JSON-RPC result includes serverInfo.name=vector, protocolVersion, and advertised resources/tools/prompts capabilities.
MCP tools/list	Response lists only tools allowed by token scopes and agent policy. Missing tools are denied, not hidden by accident.
North Graph verify	Output includes policy pass/fail, risk, impacted tests, verification command results, and limitations or degraded analyzer warnings.

CLI login

The current CLI login flow is token based.

There is no reason to give a terminal username and password. Create a scoped CLI token in the browser, put it in the terminal environment, and verify it with /cli/v1/me before running commands that mutate work.

Log in a terminal session

Create a CLI token from Developer access -> Tokens.
Copy the token immediately and store it in a shell secret, password manager, or CI secret store.
Set VECTOR_TOKEN in the terminal session that will call Vector.
Set VECTOR_BASE_URL to the Vector web app origin.
Call /cli/v1/me and verify the token belongs to the expected actor and workspace before running create, update, or comment commands.
Revoke the token from Developer access when it is no longer needed or if it appears in logs.

CLI login

Authenticate a terminal session

# Create the token in the browser:
# Workspace console -> Developer access -> Tokens -> Create token

export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_TOKEN="vta_..."

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/me"

Read before writes

Verify the actor and scopes

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/me"

{
  "requestId": "req_01H...",
  "actor": {
    "actorType": "agent",
    "actorLabel": "Local coding agent",
    "userId": "usr_..."
  },
  "token": {
    "scopes": ["workspace:read", "issue:read", "context:read"],
    "workspaceId": "wrk_..."
  },
  "workspaces": [{ "id": "wrk_...", "slug": "acme" }]
}

Terminal agent

Use a terminal agent with an MCP credential, not a browser session.

The supported agent path is explicit: create an agent identity, give it allowed teams and tools, start the agent from a local terminal, and configure it to call the Vector MCP endpoint with its own credential.

MCP surface	Runs where	Data it can see	Credential	Use it for
Vector MCP	Hosted Vector web app at /mcp	Workspace records: issues, projects, teams, comments, context bundles, linked artifact metadata where supported, approvals, and audit-backed tool calls.	MCP agent credential from Developer access	Use this when an agent needs product context or needs to create/update/comment on accessible work.
North Graph CLI + local MCP	Developer machine through vector north commands or vector north mcp	Local repository facts: files, symbols, callers, routes, effects, policy, diff risk, impacted tests, and verification reports.	Local terminal process started by the developer	Use vector north commands for humans/scripts and vector north mcp when an agent needs the same local codebase intelligence.

Developer access
MCP credential
Local terminal
Agent MCP config
Vector /mcp

Prepare a terminal coding agent

Create an agent identity from Developer access -> Agents, not from Tokens.
Choose the teams the agent may see. Private teams are invisible unless explicitly allowed.
Keep only the tools the agent needs. For read-only work, allow search_work and read_context_bundle only.
Copy the MCP token once and put it in the terminal environment or the agent's local MCP configuration.
Start the agent from your terminal with that MCP configuration loaded.
Tell the agent to use Vector MCP for issue/project context and North Graph for local codebase facts before editing.

MCP login

Verify the MCP credential from terminal

# Create the credential in the browser:
# Workspace console -> Developer access -> Agents -> Create agent

export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_MCP_TOKEN="vta_..."

curl -s -X POST "$VECTOR_BASE_URL/mcp" \
  -H "Authorization: Bearer $VECTOR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {}
  }'

Terminal agent

Make the agent use the product contracts

# Start your MCP-compatible coding agent from the terminal.
# Keep the token in env/config; do not paste it into the prompt.

export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_MCP_TOKEN="vta_..."

Prompt for the terminal agent:

Use hosted Vector MCP to read ENG-124 before planning. Use compact mode for the first pass.
Use local North Graph MCP to inspect affected symbols and impacted tests.
Do not edit auth, billing, email delivery, or private-team code.

MCP config

Configure the two MCP surfaces as separate servers.

Most MCP-capable terminal agents accept a client configuration that registers named servers. Use one server entry for hosted Vector MCP and a separate server entry for local North Graph MCP.

Hosted MCP

Generic Vector MCP client config

{
  "mcpServers": {
    "vector": {
      "transport": "http",
      "url": "${VECTOR_BASE_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${VECTOR_MCP_TOKEN}"
      }
    }
  }
}

Local MCP

Generic North Graph MCP client config

{
  "mcpServers": {
    "north-graph": {
      "command": "vector",
      "args": ["north", "mcp"]
    }
  }
}

Expected output

MCP initialize response shape

{
  "jsonrpc": "2.0",
  "id": "init-1",
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": {
      "name": "vector",
      "title": "Vector Work Management",
      "version": "0.1.0"
    },
    "capabilities": {
      "resources": { "listChanged": false },
      "tools": { "listChanged": false },
      "prompts": { "listChanged": false }
    }
  }
}

North Graph

North Graph is the local codebase-intelligence part of the Vector CLI.

Use vector north commands when a human or script needs repo facts. Use vector north mcp when a terminal agent needs those same local facts through MCP. It is separate from /cli/v1 and separate from hosted Vector MCP.

Terminal agent
Vector CLI
North Graph
Local repo index
Verification report

Less guessingAgents can ask for symbols, callers, routes, effects, policies, and impacted tests instead of reading random files until the context feels right.
Local by defaultRepository indexing, policy checks, and verification reports run on the developer's machine. Source code is not uploaded to Vector by default.
Risk is explicitNorth Graph calls out database writes, email sends, secret reads, network calls, auth checks, production config changes, and other effects.
Policy is enforceableA checked-in vector.north.json policy can mark paths as sensitive, require tests, block effects, or require human review.
Tests are easier to chooseDiff and symbol analysis can return directly covering tests, likely impacted tests, required policy tests, and missing coverage signals.
Evidence travels backReports summarize changed files, risk, policy pass/fail, commands run, limitations, and evidence that can later attach to Vector work.

Command	Use
`vector north init`	Create the local North Graph policy/config file for a repository.
`vector north index --json`	Build or refresh the local repo index for agent-readable facts.
`vector north inspect <symbol> --json`	Find a symbol definition, callers, callees, effects, policy, and tests.
`vector north effects --type secret_read --json`	List code locations that perform a sensitive effect.
`vector north diff analyze --base main --json`	Analyze changed files, new effects, policy failures, risk, and impacted tests.
`vector north verify --base main --json`	Run configured verification commands and return a structured result.
`vector north report pr --base main --out .vector/north/pr-report.json --json`	Generate a PR-ready verification report for review or future Vector evidence sync.
`vector north mcp`	Start the local North Graph MCP server for a terminal agent.

North Graph MCP tool	Use
`inspect_symbol`	Return definition, callers, callees, effects, tests, and policy for a symbol.
`find_callers`	Return local callers for a symbol or route handler.
`find_effects`	Return effect locations by effect type.
`analyze_diff`	Analyze the current git diff against a base ref.
`check_policy`	Evaluate the repo or current diff against vector.north.json.
`find_impacted_tests`	Return tests likely affected by files, symbols, or the current diff.
`summarize_risk`	Return a compact risk summary for an agent planning step.
`report_pr`	Generate the PR-ready report payload.

North Graph

Map and verify a local code change

vector north init
vector north index --json
vector north inspect scoreJob --json
vector north effects --type email_send --json
vector north diff analyze --base main --json
vector north verify --base main --json
vector north report pr \
  --base main \
  --out .vector/north/pr-report.json \
  --json

Local MCP

Expose repo intelligence to a terminal agent

# Start the local codebase-intelligence MCP server.
vector north mcp

# Then connect your terminal agent to that local MCP server.
# Use hosted Vector MCP for workspace work data.
# Use local North Graph MCP for local repo facts.

Product surfaces

The documentation covers the current workspace product, not only agents.

Use this as the map of implemented Vector surfaces before you choose the UI, CLI, hosted MCP, or North Graph. Each row includes the product capability, the contract family, and the guardrail that must stay true.

Surface	Implemented capability	Contract family	Guardrail
Canonical worklist	My Issues, team issue lists, triage, saved views, facets, grouping, sorting, pagination, bulk updates, hierarchy, estimates, reminders, and issue templates.	Workspace UI plus the documented /cli/v1 issue search and issue mutation operations.	Workspace and private-team filtering happen on the server. Facets and counts are permission-filtered, not global workspace totals.
Planning	Sprints, projects, initiatives, milestones, labels, project updates, initiative updates, owner metadata, project spec docs, and issue planning assignment.	Workspace UI plus documented issue/project context reads for scripts and agents.	Planning objects must belong to the same workspace and stay filtered by team/project access.
Workspace knowledge	Document collections, workspace docs, comments, review ownership, stale/reviewed state, pinned docs, version history, and version restore.	Workspace UI, issue/project context panels, and linked artifact metadata where supported.	Docs are workspace-owned records. Broad CLI/MCP document read-write tools are not part of the public CLI catalog today.
Canvas	First-party canvas scenes with frames, text, tables, mind maps, freehand notes, comment elements, artifact links, presence, version history, and version restore.	Workspace UI, issue/project context panels, and linked artifact metadata where supported.	Canvas scenes are stored in PostgreSQL as Vector-owned JSON and remain tenant scoped by workspace_id.
Context and artifact links	Issue/project context fields, context extraction, evidence summaries, expected outcomes, success metrics, and links between docs, canvases, issues, projects, and initiatives.	Documented /cli/v1 context endpoints, hosted MCP context resources/tools, and workspace UI context panels.	Context bundles expose permission-filtered structured facts and linked artifact metadata; compact mode reduces prompt payloads without removing source IDs, redactions, or policy metadata.
Customer intake and SLA	Customers, customer requests, public Asks, requester status pages, email intake, reply sync, SLA rules, SLA evaluation, and risk/breach notifications.	Workspace UI, public requester pages, and exported customer/request data where enabled.	Requester views never expose internal workspace, private-team, assignee, or project details unless explicitly allowed.
Feed, notifications, realtime, search, and insights	Inbox notifications, project/initiative Feed, workspace SSE updates, PostgreSQL search across indexed objects, and issue/customer/project/SLA rollups.	Workspace UI with permission-filtered search, activity, notification, and insight surfaces.	Search, notification payloads, realtime events, and analytics rollups revalidate workspace and private-team access.
Developer access and GitHub	Scoped CLI tokens, agent integration identities, allowed teams/tools, credential revocation, GitHub App install, repository enablement, and status automation settings.	Workspace UI for credential and GitHub setup, then documented CLI/MCP surfaces for programmatic use.	GitHub is the only third-party MVP integration. Product-facing docs should say agent integration identity, not fake human user.
Admin, billing, imports, and exports	Workspace settings, members, roles, billing plan state, plan downgrade checks, import dry-runs, full JSON exports, and CSV exports for issues, projects, initiatives, customers, and requests.	Workspace UI and exported files where the caller's role and plan allow it.	Owner/admin checks apply. Exports are audited and plan-gated where implemented.
North Graph	Local repo indexing, facts, symbols, callers, effects, policy checks, diff risk, impacted tests, verification commands, PR reports, and local North Graph MCP.	Local Vector CLI commands: vector north init/index/facts/inspect/effects/policy/diff/tests/verify/report/mcp.	North Graph is local-first and model-agnostic. It does not upload source code or authorize production changes.

Document product context before implementation

Create or update the workspace document in the right collection.
Link the document to the relevant issue, project, or initiative.
Set review state or review owner when the document will guide execution.
Use the issue/project context panel or context bundle so agents see the linked source.

Use canvas as execution context

Create a canvas for the diagram, table, mind map, or planning board.
Link it to the issue, project, or initiative it explains.
Save a version before major edits and use restore when a bad change lands.
Keep sensitive local paths or source snippets out unless explicitly approved.

Prepare a reliable daily worklist

Use server filters for status, assignee, priority, team, project, sprint, label, SLA, parent, and query.
Choose group and sort from the canonical worklist contract.
Save the view as personal, team, or workspace visibility.
Use the saved view route to reload counts, facets, groups, and pagination instead of filtering locally.

Workspace knowledge

Docs and canvases are first-class product records.

Workspace docs, collections, document comments, document versions, canvases, canvas presence, and canvas versions are part of the product contract. They should be linked to work instead of living as untracked side notes.

Artifact	Capabilities	Links to	Route
Document collection	Hierarchical grouping for workspace docs and canvases, with sort order and archive state.	Documents and canvases through collection_id.	Create and organize from the workspace UI.
Workspace document	Markdown body, content_json, pinned state, review owner, reviewed/stale timestamps, artifact links, and archive state.	Issues, projects, and initiatives through context_links.	Create, edit, archive, and link from the workspace UI.
Document comment	Threaded product discussion on a document, with author, edit/delete timestamps, and workspace scoping.	One document in the same workspace.	Use document comments from the workspace UI.
Document version	Immutable saved title/body/content_json snapshots, version numbers, creator, restore support, and conflict handling.	One document in the same workspace.	View and restore versions from the workspace UI.
Canvas scene	Vector-owned scene JSON for frames, text, tables, connectors, mind maps, freehand, comment elements, viewport, and links.	Issues, projects, and initiatives through context_links.	Create, edit, archive, and link from the workspace UI.
Canvas version	Immutable scene snapshots with version restore and expected-version conflict behavior.	One canvas in the same workspace.	View and restore versions from the workspace UI.
Canvas presence	Ephemeral collaboration signal for selected element IDs and collaborator color on the active canvas.	One canvas in the same workspace.	Shown automatically while collaborators work in the canvas UI.
Search document	Search index rows for issues, comments, projects, initiatives, documents, canvases, customers, and views.	Workspace search results and future context discovery.	Use workspace search and documented context surfaces.

Programmatic parity boundary

The workspace UI covers the full docs and canvas workflow today. Hosted MCP and CLI expose issue/project context and linked artifact metadata where supported, but broad document/canvas read-write tools are not part of the public CLI catalog today.

Programmatic coverage

Every major workspace surface has a documented contract boundary.

This is the product coverage view: issue work, worklists, knowledge, planning, customer intake, operator workflows, and developer access. It also states which work belongs in the workspace UI, the public CLI catalog, hosted MCP, or North Graph.

Area	Coverage	Programmatic status
Issue operations	Issues, children, comments, attachments, relations, external links, reminders, bulk update, context, and context extraction.	Public CLI catalog covers issue search, create, read, update, comment, context, and linked GitHub metadata.
Worklist operations	Canonical issue list, saved views, view execution, facets, groups, sort, cursor/offset pagination, and URL-backed state.	Workspace UI covers the full worklist. CLI/MCP expose the permission-filtered issue search subset.
Knowledge operations	Document collections, docs, comments, document versions, canvas scenes, canvas presence, canvas versions, and artifact links.	Workspace UI covers full docs/canvas workflows. CLI/MCP expose linked artifact metadata through supported context surfaces.
Planning operations	Sprints, projects, project context, project issues, milestones, labels, updates, spec docs, initiatives, initiative milestones, updates, labels, and draft updates.	Workspace UI covers full planning workflows. CLI/MCP expose selected issue/project context reads.
Customer operations	Customers, contacts, customer requests, public Asks, status tokens, email intake, reply sync, and SLA evaluation.	Workspace UI and public requester pages cover intake. No non-GitHub native integrations in MVP.
Operator operations	Admin settings, members, billing plans, plan downgrade checks, import dry-runs, JSON exports, CSV exports, Insights, Feed, notifications, realtime, and search.	Workspace UI covers operator workflows with role, plan, and audit checks where implemented.
Developer operations	CLI tokens, MCP tokens, agent integration identities, allowed tools, allowed teams, GitHub installation, repository settings, and status automation.	Workspace UI manages credentials. CLI, hosted MCP, and North Graph handle programmatic execution.

Access contract

All supported callers resolve to an actor before data access.

The server does not authorize by surface. It authorizes by actor, workspace, team policy, object permission, token scope, and tool policy where applicable.

Surface	Credential	Checks	Failure behavior
Browser UI	`Signed web session`	user_id, active workspace membership, role, private-team access	403 permission_denied or object-level not_found
CLI /cli/v1	`Bearer access token`	token hash, token scopes, workspace scope, actor membership	401 invalid_token, 403 scope_denied, or workspace_scope_denied
MCP server	`MCP bearer token`	token scopes, allowedTools, allowedTeamIds, object permission	403 agent_tool_denied, agent_team_denied, or scope_denied
GitHub sync and jobs	`Webhook signature or system actor`	signature, installation workspace, idempotency, event source	401/403 for bad source, duplicate event ignored when idempotent

Evaluation order

Authenticate the request. Browser requests use the signed web session. CLI and MCP requests use Authorization: Bearer <token>.
Resolve the actor. The server records whether the caller is a human, agent, integration, or system actor.
Bind the workspace from the route or host. A token scoped to workspace A cannot read or write workspace B.
Load workspace membership and role. Disabled, guest, requester, or missing memberships stop here.
Apply private-team filters before returning lists, search results, notifications, exports, or context bundles.
Check the endpoint or tool scope. Examples: issue:read, issue:write, context:read, mcp:tools, comment:write.
Check agent policy when actorType is agent. allowedTools and allowedTeamIds must both permit the operation.
Write activity or audit records for mutations and sensitive reads, including requestId and actor attribution.

Objects

Core records and the guardrails around them.

These records appear in API responses and context bundles. The guard column lists the minimum authorization boundary before the record can be returned.

Object	Identifiers	Required fields	Use	Guard
Workspace	`workspace_id, slug`	name, slug, membership records	Tenant boundary for all product data.	workspace membership required
Team	`team_id, identifier`	workspace_id, name, identifier, visibility	Owns workflow statuses, issues, labels, sprints, and private visibility.	workspace membership plus private-team access
Issue	`issue_id, issueIdentifier`	workspace_id, team_id, title, status, priority	Smallest durable unit of tracked work.	workspace membership, team access, object permission
Comment	`comment_id`	workspace_id, issue_id, actor, body	Conversation and handoff record attached to an issue.	workspace membership and issue access
Project	`project_id`	workspace_id, title, status/health, owner	Groups issues into a larger delivery outcome.	workspace membership and private-team filtering
Sprint	`sprint_id`	workspace_id, team_id, name, status, start/end dates	Time-boxes team issue planning and progress.	workspace membership and planning permission for writes
Initiative	`initiative_id`	workspace_id, title, status, owner	Connects projects, milestones, updates, labels, and higher-level outcomes.	workspace membership and planning permission for writes
Saved view	`view_id`	workspace_id, owner/visibility, filters, grouping, sorting	Stores canonical worklist filters and layout.	workspace membership plus saved-view visibility
Document collection	`collection_id`	workspace_id, name, hierarchy metadata	Groups workspace docs and canvases for queryable knowledge.	workspace membership and shared-object access
Workspace document	`document_id`	workspace_id, title, body/content_json, version_number	Durable workspace knowledge with review, stale, pinned, and version history state.	workspace membership and linked-object access where applicable
Document comment/version	`document_comment_id, version_number`	workspace_id, document_id, body or snapshot metadata	Captures discussion and recoverable document history.	workspace membership and document access
Canvas	`canvas_id`	workspace_id, title, scene_json, version_number	First-party visual planning and architecture surface with version restore.	workspace membership and linked-object access where applicable
Template	`template_id`	workspace_id, type, title, body/schema	Reusable issue, form, project, and document starting points.	workspace membership and template visibility
SLA or recurring rule	`sla_rule_id, recurring_issue_id`	workspace_id, schedule/threshold, target metadata	Automates service expectations and repeated work creation.	workspace membership and plan/role checks
Customer request	`customer_id, request_id`	workspace_id, source, customer/request metadata	Connects customer signal to issues and projects.	workspace membership and linked-object access
Notification or Feed entry	`notification_id, feed_entry_id`	workspace_id, actor, object, event metadata	Inbox and activity stream records for workspace execution.	workspace membership and channel/object access
Developer access record	`access_token_id, agent_principal_id`	workspace_id, principal, scopes, allowed tools/teams	Creates revocable CLI and MCP credentials without storing raw token values.	owner/admin/member rules plus token/tool policy

CLI API

/cli/v1 is the public CLI contract for scripts.

Send Authorization: Bearer <token>. Mutations that can duplicate work should include Idempotency-Key. Responses include requestId where useful.

Method	Path	Scopes	Body / query	Returns
`GET`	`/cli/v1/me`	workspace:read	none	actor, token scopes, scoped workspace, accessible workspaces
`GET`	`/cli/v1/workspaces`	workspace:read	none	workspaces visible to the token
`GET`	`/cli/v1/workspaces/{workspaceId}/teams`	workspace:read, team:read	none	accessible teams only
`GET`	`/cli/v1/workspaces/{workspaceId}/issues`	workspace:read, issue:read	query, teamId, statusId, assigneeUserId, priority, projectId, sprintId, labelId, limit	permission-filtered issue list
`POST`	`/cli/v1/workspaces/{workspaceId}/issues`	workspace:read, team:read, issue:write	teamId, title, description?, priority?, statusId?, assigneeUserId?	created issue and requestId
`GET`	`/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}`	workspace:read, issue:read	none	issue detail if accessible
`PATCH`	`/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}`	workspace:read, issue:write	title?, description?, priority?, statusId?, assigneeUserId?, sprintId?, projectId?	updated issue
`POST`	`/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/comments`	workspace:read, comment:write	body	created comment
`GET`	`/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/context`	workspace:read, issue:read, context:read	none	issue context bundle JSON; use ?mode=compact for a smaller provider-neutral payload
`GET`	`/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/github`	workspace:read, issue:read	none	linked pull requests, branches, commits visible to the issue
`GET`	`/cli/v1/workspaces/{workspaceId}/projects/{projectId}/context`	workspace:read, context:read	none	project context bundle JSON; use ?mode=compact for a smaller provider-neutral payload

Read before writes

Verify the actor and scopes

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/me"

{
  "requestId": "req_01H...",
  "actor": {
    "actorType": "agent",
    "actorLabel": "Local coding agent",
    "userId": "usr_..."
  },
  "token": {
    "scopes": ["workspace:read", "issue:read", "context:read"],
    "workspaceId": "wrk_..."
  },
  "workspaces": [{ "id": "wrk_...", "slug": "acme" }]
}

Mutation

Create an issue with retry safety

curl -s -X POST \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-checkout-telemetry-001" \
  -d '{
    "teamId": "team_...",
    "title": "Add checkout retry telemetry",
    "description": "Record retry reason, attempt count, and final result.",
    "priority": "high"
  }' \
  "$VECTOR_BASE_URL/cli/v1/workspaces/wrk_.../issues"

{
  "requestId": "req_01H...",
  "issue": {
    "id": "iss_...",
    "identifier": "ENG-124",
    "title": "Add checkout retry telemetry"
  }
}

Public API catalog

The supported CLI operations are listed like an API reference.

Every operation here is callable with a CLI token and the documented scopes. Use this catalog for terminal scripts and automation that should behave the same way across environments.

Rule	Contract
Base URL	Set VECTOR_BASE_URL to the Vector app origin. Every CLI API path below is relative to that origin.
Authentication	Send Authorization: Bearer $VECTOR_TOKEN on every request.
JSON	Send Content-Type: application/json on requests with a body. Responses are JSON and include requestId where useful.
Workspace binding	Use workspaceId returned by /cli/v1/me. Do not guess it from a slug or UI label.
Idempotency	Send Idempotency-Key on retryable POST/PATCH calls that could duplicate work.
Errors	Branch on error.code. Do not parse human-readable messages.

GET/cli/v1/me

Verify the caller before any other request.

Auth: Bearer CLI token
Scopes: workspace:read
Path params: none
Query: none
Body: none
Returns: requestId, actor, token scopes, scoped workspaceId, accessible workspaces
Idempotency: not applicable
Common errors: invalid_token, scope_denied

GET/cli/v1/workspaces

List accessible workspaces for the token.

Auth: Bearer CLI token
Scopes: workspace:read
Path params: none
Query: none
Body: none
Returns: workspaces visible to the token owner
Idempotency: not applicable
Common errors: invalid_token, scope_denied

GET/cli/v1/workspaces/{workspaceId}/teams

List teams the caller can use.

Auth: Bearer CLI token
Scopes: workspace:read, team:read
Path params: workspaceId
Query: none
Body: none
Returns: teams visible to the caller
Idempotency: not applicable
Common errors: invalid_token, workspace_scope_denied, scope_denied

GET/cli/v1/workspaces/{workspaceId}/issues

Search and filter issues for scripts.

Auth: Bearer CLI token
Scopes: workspace:read, issue:read
Path params: workspaceId
Query: query?, teamId?, statusId?, assigneeUserId?, priority?, projectId?, sprintId?, labelId?, limit?
Body: none
Returns: permission-filtered issue list
Idempotency: not applicable
Common errors: invalid_token, workspace_scope_denied, scope_denied

POST/cli/v1/workspaces/{workspaceId}/issues

Create an issue from a script.

Auth: Bearer CLI token
Scopes: workspace:read, team:read, issue:write
Path params: workspaceId
Query: none
Body: teamId, title, description?, priority?, statusId?, assigneeUserId?
Returns: created issue and requestId
Idempotency: recommended
Common errors: invalid_token, workspace_scope_denied, scope_denied, permission_denied, idempotency_key_conflict

GET/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}

Read one issue by identifier.

Auth: Bearer CLI token
Scopes: workspace:read, issue:read
Path params: workspaceId, issueIdentifier
Query: none
Body: none
Returns: issue detail if accessible
Idempotency: not applicable
Common errors: invalid_token, workspace_scope_denied, scope_denied, not_found

PATCH/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}

Update supported issue fields.

Auth: Bearer CLI token
Scopes: workspace:read, issue:write
Path params: workspaceId, issueIdentifier
Query: none
Body: title?, description?, priority?, statusId?, assigneeUserId?, sprintId?, projectId?
Returns: updated issue
Idempotency: recommended when retrying
Common errors: invalid_token, workspace_scope_denied, scope_denied, not_found, idempotency_key_conflict

POST/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/comments

Add a comment to an issue.

Auth: Bearer CLI token
Scopes: workspace:read, comment:write
Path params: workspaceId, issueIdentifier
Query: none
Body: body
Returns: created comment
Idempotency: recommended
Common errors: invalid_token, workspace_scope_denied, scope_denied, not_found, idempotency_key_conflict

GET/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/context

Read implementation context for one issue.

Auth: Bearer CLI token
Scopes: workspace:read, issue:read, context:read
Path params: workspaceId, issueIdentifier
Query: mode=standard|compact
Body: none
Returns: permission-filtered issue context bundle with tokenEfficiency metadata
Idempotency: not applicable
Common errors: invalid_token, workspace_scope_denied, scope_denied, not_found

GET/cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/github

Read linked GitHub development metadata.

Auth: Bearer CLI token
Scopes: workspace:read, issue:read
Path params: workspaceId, issueIdentifier
Query: none
Body: none
Returns: linked pull requests, branches, and commits visible to the issue
Idempotency: not applicable
Common errors: invalid_token, workspace_scope_denied, scope_denied, not_found

GET/cli/v1/workspaces/{workspaceId}/projects/{projectId}/context

Read delivery context for one project.

Auth: Bearer CLI token
Scopes: workspace:read, context:read
Path params: workspaceId, projectId
Query: mode=standard|compact
Body: none
Returns: permission-filtered project context bundle with tokenEfficiency metadata
Idempotency: not applicable
Common errors: invalid_token, workspace_scope_denied, scope_denied, not_found

CLI workflows

CLI workflows are JSON contracts for scripts.

Use the CLI surface for deterministic terminal and CI workflows. Verify identity first, use returned IDs, preserve request IDs, and use idempotency for retryable writes.

Workflow	Endpoint	Production guidance
Verify identity	GET /cli/v1/me	Run first in every new environment. Confirms actor, scopes, workspace, and requestId.
Discover teams	GET /cli/v1/workspaces/{workspaceId}/teams	Use returned team IDs. Do not guess private-team identifiers from UI labels.
Search issues	GET /cli/v1/workspaces/{workspaceId}/issues	Returns permission-filtered results. Missing private issues may appear as not_found elsewhere.
Create issue	POST /cli/v1/workspaces/{workspaceId}/issues	Use Idempotency-Key when a retry could create duplicates.
Update issue	PATCH /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}	Updates allowed fields only. Planning fields must still belong to the accessible team/project.
Add comment	POST /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/comments	Use for script or agent handoff notes. Keep secrets and raw local paths out.
Read context	GET /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/context	Use before implementation planning. Response is structured, source-linked, and permission filtered.
Read linked development metadata	GET /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/github	Use for GitHub-linked PR, branch, and commit metadata visible to that issue. Do not treat it as a source-code API.
Read project context	GET /cli/v1/workspaces/{workspaceId}/projects/{projectId}/context	Use for delivery context that spans multiple issues. Project access and private-team filtering still apply.

Discover teams

Use returned IDs instead of guessing

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/workspaces/wrk_.../teams"

{
  "requestId": "req_01H...",
  "teams": [
    {
      "id": "team_...",
      "identifier": "ENG",
      "name": "Engineering",
      "visibility": "public"
    }
  ]
}

Context

Read implementation context through CLI

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/workspaces/wrk_.../issues/ENG-124/context"

{
  "requestId": "req_01H...",
  "bundle": {
    "issue": { "identifier": "ENG-124" },
    "permissionDecisions": [],
    "redactions": [],
    "freshness": { "generatedAt": "2026-05-15T04:00:00.000Z" }
  }
}

Handoff

Leave a verifiable comment

curl -s -X POST \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-handoff-ENG-124-001" \
  -d '{
    "body": "Verified with vector north verify --base main. Request IDs: req_01H..."
  }' \
  "$VECTOR_BASE_URL/cli/v1/workspaces/wrk_.../issues/ENG-124/comments"

MCP workflows

Hosted Vector MCP is for permissioned workspace work.

An agent should discover capabilities first, read context before planning, mutate only through allowed tools, and request approval when the task crosses a denied or high-risk boundary.

Workflow	Method or tool	Production guidance
Initialize	initialize	Confirms protocol version, server identity, and available capability classes.
Discover capabilities	tools/list, resources/templates/list, prompts/list	Capability discovery is permission-filtered. Missing tools are expected when policy denies them.
Read context	read_context_bundle or resources/read	Use for issue context before planning, editing, or summarizing work.
Search work	search_work	Use for accessible issue discovery. Results are filtered by workspace and team policy.
Mutate work	create_issue, update_issue, add_comment	Requires mcp:tools plus the action scope. Use idempotencyKey for retryable writes.
Request approval	request_approval	Use when a task needs a human decision or reaches an MVP-denied action boundary.
Respect parity boundaries	context resources and explicit tools only	Hosted MCP does not provide broad workspace-admin, billing, export, GitHub-install, document-write, or canvas-write authority in MVP.

MCP write

Create an issue through hosted Vector MCP

{
  "jsonrpc": "2.0",
  "id": "create-1",
  "method": "tools/call",
  "params": {
    "name": "create_issue",
    "arguments": {
      "workspaceId": "wrk_...",
      "teamId": "team_...",
      "title": "Add retry telemetry",
      "description": "Record retry reason, attempt count, and final result.",
      "priority": "high",
      "idempotencyKey": "create-retry-telemetry-001"
    }
  }
}

Approval

Stop at risky boundaries

{
  "jsonrpc": "2.0",
  "id": "approval-1",
  "method": "tools/call",
  "params": {
    "name": "request_approval",
    "arguments": {
      "workspaceId": "wrk_...",
      "action": "Run production-impacting migration",
      "reason": "The task touches workspace isolation and requires owner approval.",
      "riskLevel": "critical"
    }
  }
}

North Graph workflows

Use North Graph for local codebase evidence.

Use North Graph before and after code edits. It should identify affected code, sensitive effects, policy failures, impacted tests, verification output, and limitations.

Workflow	Command	Production guidance
Initialize repo policy	vector north init	Creates or prepares vector.north.json so the repo can define effect and review rules.
Build local index	vector north index --json	Generates local codebase facts for supported languages and config files.
Inspect before editing	vector north inspect <symbol> --json	Finds definitions, callers, effects, policy, and tests before the agent changes code.
Analyze risk	vector north diff analyze --base main --json	Shows changed files/symbols, new effects, policy failures, risk, and impacted tests.
Verify	vector north verify --base main --json	Runs configured verification commands and reports pass/fail with limitations.
Share evidence	vector north report pr --base main --out .vector/north/pr-report.json --json	Produces a structured report suitable for review or future Vector evidence sync.

Policy

Example vector.north.json policy

{
  "version": 1,
  "rules": [
    {
      "name": "recommendations cannot send email",
      "paths": ["src/recommendations/**"],
      "deniedEffects": ["email_send", "secret_read", "payment_operation"],
      "requiredTests": ["ranking.test.ts"]
    },
    {
      "name": "auth requires human review",
      "paths": ["src/auth/**", "src/permissions/**"],
      "risk": "critical",
      "requiresHumanReview": true
    }
  ]
}

Evidence

North Graph report shape

{
  "reportId": "north_01H...",
  "baseRef": "main",
  "risk": "medium",
  "policy": { "passed": true },
  "changedFiles": ["src/recommendations/ranking.ts"],
  "newEffects": [],
  "impactedTests": ["ranking.test.ts", "email-alert-job-selection.test.ts"],
  "verification": [
    { "command": "pnpm test ranking.test.ts", "status": 0 }
  ],
  "limitations": []
}

MCP

MCP exposes resources, tools, and prompts under the same policy model.

Agents only see tools allowed by both token scopes and agent policy. Tool calls are audited with actor, workspace, tool, object, and request ID.

Tool	Required scopes	Arguments
`search_work`	mcp:read or issue:read	workspaceId, query?, teamId?, statusId?, assigneeUserId?, priority?, projectId?, sprintId?, labelId?, limit?
`create_issue`	mcp:tools, issue:write, team:read	workspaceId, teamId, title, description?, priority?, statusId?, assigneeUserId?, idempotencyKey?
`update_issue`	mcp:tools, issue:write	workspaceId, issueIdentifier, title?, description?, priority?, statusId?, assigneeUserId?, sprintId?, projectId?, idempotencyKey?
`add_comment`	mcp:tools, comment:write	workspaceId, issueIdentifier, body, idempotencyKey?
`read_context_bundle`	mcp:read, issue:read, context:read	workspaceId, issueIdentifier, mode?
`request_approval`	approval:request	workspaceId, action, reason, riskLevel?

MCP login

Verify the MCP credential from terminal

# Create the credential in the browser:
# Workspace console -> Developer access -> Agents -> Create agent

export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_MCP_TOKEN="vta_..."

curl -s -X POST "$VECTOR_BASE_URL/mcp" \
  -H "Authorization: Bearer $VECTOR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {}
  }'

Discovery

Confirm what the agent is allowed to do

curl -s -X POST "$VECTOR_BASE_URL/mcp" \
  -H "Authorization: Bearer $VECTOR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "method": "tools/list"
}'

{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "result": {
    "tools": [
      { "name": "search_work" },
      { "name": "read_context_bundle" }
    ]
  }
}

Context

Read an issue context bundle

curl -s -X POST "$VECTOR_BASE_URL/mcp" \
  -H "Authorization: Bearer $VECTOR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": "ctx-1",
  "method": "tools/call",
  "params": {
    "name": "read_context_bundle",
    "arguments": {
      "workspaceId": "wrk_...",
      "issueIdentifier": "ENG-124",
      "mode": "compact"
    }
  }
}'

{
  "structuredContent": {
    "contextBundle": {
      "issue": { "identifier": "ENG-124" },
      "comments": [],
      "activity": [],
      "permissionDecisions": [],
      "redactions": [],
      "requestId": "req_01H...",
      "tokenEfficiency": { "mode": "compact" }
    }
  }
}

Context bundles

Context bundles are the agent-safe package of issue facts.

They are not free-form summaries. They are structured, permission-filtered JSON with source IDs, timestamps, redaction markers, and request metadata.

issue title, description, identifier, status, priority, assignee, team
project, sprint, milestone, initiative, customer request, label, SLA, and parent/child planning metadata where accessible
queryable context fields such as intent, expected outcome, architecture constraint, evidence summary, success metric, guardrail metric, outcome, and learning
comments and activity/history with actor type
attachment metadata only, not raw file bytes
linked artifact metadata for accessible workspace docs, canvases, issues, projects, and initiatives
issue relations and accessible external links
source object IDs, timestamps, requestId, and freshness metadata
permission decisions and redaction markers

Permissions

A token never gives more access than the actor has in the workspace.

Use this table to decide whether a failed request is missing membership, object access, token scope, or agent policy.

Action	Human rule	Agent rule
Read issue	workspace membership + team visibility	issue:read + allowed team
Create issue	member-or-higher role with team access	issue:write + team:read + create_issue tool
Add comment	issue access + comment permission	comment:write + add_comment tool
Read context bundle	issue access; exposed through supported surfaces	context:read + read_context_bundle tool; optional compact mode keeps source IDs and policy metadata
Use saved views and canonical worklists	workspace membership + view visibility + team filters	issue:read through search_work subset
Read or update workspace docs/canvases	workspace membership + shared-object access; member+ for writes where implemented	broad doc/canvas tools deferred in MVP
Create templates, recurring issues, planning records, or SLA rules	member/admin/owner role plus plan and object checks	denied unless exposed through a future scoped tool
Read search, notifications, Feed, Insights, or exports	workspace membership with private-team/object filtering; export is owner/admin	search_work/context subset only in MVP
Manage CLI tokens, agent identities, GitHub, billing, or members	role-specific owner/admin/member checks	admin, billing, export, security, and github install scopes denied in MVP
Admin, billing, exports, members, GitHub install management	owner/admin only where implemented	denied in MVP

Runtime contracts

Production clients must handle more than the happy path.

Every integration should be written around request IDs, pagination, idempotency, structured errors, permission-filtered not_found responses, and rate-limit backoff.

Contract	Required behavior
Request IDs	Keep requestId from success and failure responses. It is the first debugging handle for support, audit, and incident review.
Pagination	List clients must handle pageInfo and server-enforced limits. Do not assume a single response contains all workspace data.
Idempotency	Retryable creates and MCP mutations should send an idempotency key. Reusing a key with different input is a conflict.
Structured errors	Branch on error.code, not message text. Messages are for humans and may change.
429 handling	Clients must treat rate limits as retryable only after backoff. Do not tight-loop CLI or MCP calls.
404 behavior	not_found can mean missing or intentionally hidden by permissions. Do not infer private object existence.
Version conflicts	Document and canvas updates should pass the expected version number. A conflict means reload and reconcile before retrying.
Plan enforcement	Billing, issue creation, private teams, exports, Asks, customer requests, Insights, and SLA actions may return 402 when the plan blocks the operation.
Programmatic parity	The workspace UI intentionally has broader product controls than CLI/MCP for docs, canvases, admin, billing, exports, and GitHub installation management.

Errors

Handle stable error codes

{
  "error": {
    "code": "agent_team_denied",
    "message": "Agent is not allowed to access this team.",
    "requestId": "req_01H..."
  }
}

// Client behavior:
// 1. Preserve requestId.
// 2. Branch on error.code.
// 3. Do not retry with a broader token unless a human changes policy.
// 4. Treat not_found as possibly permission-filtered.

Security checklist

Keep the same boundaries across humans, scripts, and agents.

Programmatic access should never become a shortcut around workspace membership, private teams, source privacy, or human accountability.

Control	Required behavior
Least privilege	Grant only the scopes, teams, and tools the script or agent needs for the current job.
No browser scraping	Use CLI/MCP contracts for programmatic work. Browser UI is for humans and setup/review.
No token leakage	Keep tokens out of prompts, source, issue comments, logs, screenshots, and generated reports.
Private-team safety	Treat missing data as possibly permission-filtered. Never ask a broader token to work around private-team denials.
Source privacy	North Graph keeps source local by default. Do not upload source snippets, local paths, or terminal output without approval.
Knowledge privacy	Docs, canvases, search results, artifact links, context bundles, exports, Feed, and notifications must be workspace scoped and private-team filtered.
Plan and admin boundaries	Do not hand an agent billing, export, member-management, GitHub installation, or security-admin work in MVP.
Human accountability	Agent credentials are owned by a human. Risky boundaries should request approval instead of proceeding.

Handoff

A useful agent handoff includes evidence, not just prose.

Humans need to see what context was read, what changed, what verification ran, what failed, and what still needs approval. Keep request IDs and report IDs attached.

Before marking agent work ready

Record the Vector context bundle requestId.
Record the North Graph report ID or command output summary.
List changed files, new effects, and policy results.
List verification commands and results.
Call out limitations, skipped checks, and approval-required work.

Handoff

Production-ready agent handoff template

Agent handoff for ENG-124

Context read:
- Vector context bundle: req_01H...
- North Graph report: north_01H...

Changes:
- Files changed:
- New effects:
- Risk:

Verification:
- Commands run:
- Results:
- Limitations:

Follow-up:
- Approval required:
- Remaining risks:

Troubleshooting

Debug with actor, scope, workspace, and request ID first.

Most production failures are credential, scope, workspace, private-team, idempotency, or missing-context problems. These cases should be diagnosable without exposing secrets.

Symptom	Likely cause	Fix
Token works locally but fails in CI	CI secret has whitespace, wrong token, expired token, or different VECTOR_BASE_URL.	Print only token prefix, call /cli/v1/me, compare workspaceId and scopes, then rotate if exposed.
MCP tools/list is missing a tool	The agent credential lacks scope, allowedTools entry, team access, or owner membership.	Inspect Developer access -> Agents, then recreate or adjust the agent identity with least privilege.
Issue exists in UI but API returns not_found	The issue is in a private team, another workspace, or the token owner lacks access.	Use workspaceId from /cli/v1/me and verify team access. Do not infer private issue existence.
Create request duplicated work	Retry happened without an idempotency key or with different input.	Use a stable Idempotency-Key for the exact request body and handle idempotency_key_conflict.
North Graph reports unexpected risk	The diff introduced or touched a sensitive effect, protected path, policy rule, or required test.	Inspect the report limitation/policy fields, then either change the code or ask a human to approve the risk.
Agent gives generic plans	The agent did not read a context bundle or local North Graph facts before planning.	Require read_context_bundle and relevant north inspect/diff commands before accepting a plan.
Document or canvas save shows conflict	Another client saved a newer version after the current editor loaded.	Reload the latest artifact version, compare the changes, and retry with the current expectedVersionNumber.
Feature returns 402	The workspace plan has reached a limit or the feature requires a higher plan.	Check Admin -> Billing and current usage before retrying the action or downgrade.
Search misses a document or canvas	The artifact is archived, not linked as expected, not indexed yet, or permission-filtered for the caller.	Check collection/archive state, linked objects, workspace membership, private-team access, and search indexing health.

Glossary

Terms used across the docs.

Use these exact meanings in prompts, scripts, issue comments, handoffs, and support reports.

Term	Meaning
workspace_id	Tenant boundary for workspace-owned data.
team_id	Execution group inside a workspace. Private teams require explicit membership.
issueIdentifier	Human-facing issue key such as ENG-124.
requestId	Stable request/debug identifier returned by API, CLI, and MCP surfaces.
context bundle	Permission-filtered structured JSON package of issue/project facts for humans and agents.
saved view	Stored worklist query, grouping, sorting, filters, and visibility for a workspace or user.
workspace document	Versioned, reviewable workspace knowledge record that can link to work and planning artifacts.
canvas	First-party visual workspace artifact stored as Vector-owned scene JSON with version history.
artifact link	Permission-checked link between docs, canvases, issues, projects, and initiatives.
template	Reusable issue, form, project, or document starting point.
SLA rule	Workspace rule that evaluates customer/request timing risk.
Feed entry	Workspace activity item for project and initiative execution updates.
North Graph report	Local verification report summarizing changed files, risk, policy, tests, limitations, and evidence.
agent identity	Non-human actor with accountable owner, scoped credential, allowed tools, and allowed teams.
hosted Vector MCP	The /mcp endpoint for workspace records and work-management tools.
local North Graph MCP	The local MCP server started by the Vector CLI with vector north mcp.

Recipes

Use these sequences as implementation templates.

The examples show the intended order of operations. Verify actor state first, then read context, then mutate with idempotency when retries are possible.

Create an issue from a script

GET /cli/v1/me and confirm workspaceId and scopes.
GET /cli/v1/workspaces/{workspaceId}/teams and choose an accessible team.
POST /cli/v1/workspaces/{workspaceId}/issues with Idempotency-Key.
Store the returned issueIdentifier for branch naming or follow-up comments.

Let an agent prepare implementation context

Create an MCP credential with mcp:read, issue:read, context:read.
Allow the read_context_bundle tool and only the teams it should see.
Call tools/list to confirm the tool is discoverable.
Call read_context_bundle and pass the returned JSON to the agent.

Errors

Handle errors by code, not by prose message.

HTTP and CLI responses use a stable error object. MCP returns JSON-RPC errors with a stable data.code and data.status.

Code	Status	Meaning
invalid_token	401	Token is missing, expired, revoked, or malformed.
scope_denied	403	The token does not include a required scope.
workspace_scope_denied	403	The token is scoped to another workspace.
agent_tool_denied	403	The agent identity is not allowed to use that MCP tool.
agent_team_denied	403	The agent identity is not allowed to access that team.
permission_denied	403	The actor is authenticated but cannot access the object.
not_found	404	The object is missing or intentionally hidden.
idempotency_key_conflict	409	The same idempotency key was reused with different input.
document_version_conflict	409	The document changed since the client version being updated or restored.
canvas_version_conflict	409	The canvas changed since the client version being updated or restored.
plan_limit_exceeded	402	The workspace has reached a limit for its current plan.
plan_upgrade_required	402	The requested capability requires a higher workspace plan.

Troubleshooting

Common failure modes.

Most failures are scope, workspace, team-policy, or credential issues. Always keep the requestId from failed calls.

Symptom	Likely cause	Fix
CLI calls return 401 or invalid_token.	The token lacks workspace:read or is expired/revoked.	Call GET /cli/v1/me with the same Authorization header and inspect error.code and requestId.
MCP tool is missing or returns agent_tool_denied.	The agent is missing a tool grant, team grant, or scope.	Compare tools/list output with the intended tool, then check allowed tools, allowed teams, and token scopes.
An issue exists in the UI but API/MCP returns not_found.	The issue belongs to a private team or another workspace.	Use the exact workspaceId from /cli/v1/me and verify team access before treating it as missing data.
Saving a document or canvas returns document_version_conflict or canvas_version_conflict.	Another browser tab or collaborator saved a newer document or canvas version.	Reload the artifact, compare the latest version, and retry with the current expectedVersionNumber.
Billing, issue creation, private teams, exports, Asks, customer requests, Insights, or SLA actions return 402.	The workspace plan blocks the requested action or downgrade.	Open Admin -> Billing, check current usage, then upgrade or reduce usage before retrying.