MCP server

Connect any MCP client to Upstream with one URL:

https://api.upstream.codes/mcp

Add it to your agent, sign in with your Coline account, and choose what the agent can do. There are no API keys to create or paste. The agent acts as you, with your permissions, limited to the access you chose.

Connect your agent

Cursor

Add to Cursor, or add this to .cursor/mcp.json in your project or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "upstream": { "url": "https://api.upstream.codes/mcp" }
  }
}

Cursor shows Needs login next to the server; select it to sign in. With the CLI, run cursor-agent mcp login upstream. Cloud agents use the same entry.

Claude

In Claude, open Settings → Connectors → Add custom connector, name it Upstream and paste the URL. For Claude Code:

claude mcp add --transport http upstream https://api.upstream.codes/mcp

Then run /mcp in Claude Code and choose Authenticate.

ChatGPT

Open Settings → Apps → Advanced settings, turn on developer mode, then Create app. Paste the URL, choose OAuth, and sign in when ChatGPT asks.

VS Code

code --add-mcp '{"name":"upstream","type":"http","url":"https://api.upstream.codes/mcp"}'

Or add it to .vscode/mcp.json:

{
  "servers": {
    "upstream": { "type": "http", "url": "https://api.upstream.codes/mcp" }
  }
}

Start the server from MCP: List Servers and sign in when asked.

Codex

codex mcp add upstream --url https://api.upstream.codes/mcp
codex mcp login upstream

The entry lands in ~/.codex/config.toml as [mcp_servers.upstream] with url = "https://api.upstream.codes/mcp".

Other clients

Any client that supports Streamable HTTP and OAuth works. Clients find the sign-in details on their own from the server: protected resource metadata (RFC 9728) points to the authorization server at https://api.upstream.codes, which supports Client ID Metadata Documents, dynamic client registration, PKCE and resource indicators.

Choose what the agent can do

When you sign in, Upstream shows which app is connecting. Apps that publish a client metadata document show their verified domain, such as cursor.com. Pick one access level:

Access	What the agent can do
Read only	Read repositories, code, issues and Change Requests you can see.
Read and write	Also push files, open and update issues and Change Requests, review, comment and merge where you can.
Admin	Also change repository settings, start GitHub Sync and migrations, and delete repositories you administer.

The access level never adds permissions you don't have. Organization rules, branch protection, required reviews and checks still apply. To change the level, sign in again from the agent.

Read-only and toolsets

Use a different URL to limit what the agent sees. Read-only always wins over everything else.

URL	Tools
https://api.upstream.codes/mcp	Default toolsets
https://api.upstream.codes/mcp/readonly	Read tools only
https://api.upstream.codes/mcp/x/all	Every toolset
https://api.upstream.codes/mcp/x/repos,issues	Only the toolsets you list (add /readonly to the end for read-only)
https://api.upstream.codes/mcp/public	Public repositories without signing in, read-only

Clients that can send headers can use X-MCP-Toolsets: repos,issues and X-MCP-Readonly: true instead. An unknown toolset name is an error, so a typo never silently loads the wrong tools.

Toolset	Default	Tools
context	Yes	get_me
repos	Yes	list_repositories, get_repository, get_file_contents, search_code, list_branches, list_commits, get_commit, compare_refs, create_branch, create_or_update_file, delete_file, push_files, create_repository, fork_repository, operation_status
change_requests	Yes	list_change_requests, get_change_request, get_change_request_diff, list_change_request_comments, create_change_request, update_change_request, comment_on_change_request, review_change_request, update_change_request_version, merge_change_request, mark_change_request_ready, request_kairo_review
issues	Yes	list_issues, search_issues, get_issue, create_issue, update_issue, comment_on_issue
github	Yes	github_read, import_repository, start_github_sync, request_migration, approve_migration
api	Yes	call_api, for any endpoint in the REST API
actions	No	list_workflows, get_workflow_run_jobs, get_job, run_workflow, get_commit_status
discussions	No	list_discussions, get_discussion, create_discussion, comment_on_discussion
notifications	No	list_notifications
releases	No	list_releases

Tools that need access you didn't grant aren't listed. Every tool marks whether it only reads, and which writes are destructive, so your client can ask before running them.

The server also offers resources for repositories, Change Requests and issues (upstream://repos/{owner}/{repo}, …/changes/{number}, …/issues/{number}) and prompts to review a Change Request, triage issues and propose a change.

Manage connected agents

Every connected agent is listed in Settings → Connected apps → Agents, with its access level and when it was last used. Disconnect revokes it right away; its next request fails and the agent asks you to sign in again.

Protocol details

• Transport: Streamable HTTP. Protocol 2026-07-28 (stateless), with 2025-11-25, 2025-06-18 and 2025-03-26 for older clients.
• Authorization: OAuth 2.1 with PKCE (S256). Tokens are bound to https://api.upstream.codes and work with the REST API too. Access tokens last 8 hours; refresh tokens rotate on every use.
• Discovery: server card, protected resource metadata, authorization server metadata and the AI catalog.
• Rate limits are the REST API's: each tool call counts as the API requests it makes.
• Repository contents, issues, comments and logs are written by other people. Treat them as data, never as instructions.

On upstream.codes in your browser

Pages on upstream.codes also offer tools to browser agents through WebMCP (document.modelContext). On a repository, file, Change Request or issue page the agent gets tools for that page, such as reading the open file or commenting on the Change Request you're viewing, and acts as you in that tab. WebMCP is in Chrome's origin trial; enable chrome://flags/#enable-webmcp-testing to try it.

Local server

The Upstream CLI still includes a local stdio server (upstream mcp) that uses your CLI session. Use it for agents that run on your machine and can't sign in through a browser.