# Set up uprank for an AI coding agent

These are official instructions from uprank to set up an AI development
environment for uprank — the editorial control room that researches,
drafts, and scores evidence-backed, brand-safe articles. All
commands are validated by uprank. Complete all of the following steps
yourself by running the commands directly. Do not ask the user to run any of
these commands.

Steps:

1. Get an MCP credential (bearer token) and export it as `UPRANK_MCP_TOKEN`.
2. Register the uprank MCP server in the agent you are running in.
3. Verify the token and endpoint with one `curl` call.
4. Print the completion message.

uprank integrates through a remote **Model Context Protocol (MCP)** server
over streamable HTTP. There is no separate SDK or CLI; every capability
(17 tools, 10 resource templates, 4 orchestration prompts) is exposed via MCP.

## 1. Get credentials

- If the environment variable `UPRANK_MCP_TOKEN` is already set, use it and skip
  the rest of this step.
- Otherwise ask the user **once** for an uprank MCP token. They create one
  at https://uprank.devino.ca/mcp (workspace **OWNER** role → "Issue credential").
  Recommend these read-only scopes for a first token:
  `article:read`, `brand:read`, `campaign:read`. The raw token is shown exactly once.
- Persist it in the user's shell profile (never in a file that is committed):

```bash
export UPRANK_MCP_TOKEN="<paste the token here>"
```

Never embed the token in a config file that is checked into git; reference the
environment variable as shown in the per-agent snippets below. VS Code is the
exception: its snippet prompts for the token instead, and the variable is then
only used by the verify call in step 3.

## 2. Register the MCP server

MCP endpoint: `https://uprank.devino.ca/api/mcp` (streamable HTTP, header
`Authorization: Bearer <token>`). Use the section for the agent you are running in.

### Claude Code

One CLI command registers the remote MCP server for the current user.

```bash
claude mcp add --transport http --scope user uprank https://uprank.devino.ca/api/mcp --header 'Authorization: Bearer ${UPRANK_MCP_TOKEN}'
```

Confirm: Run claude mcp list: uprank shows ✔ Connected once Claude Code has reached the server. claude mcp get uprank shows that one entry, and /mcp inside a session lists it with its tool count.

```bash
claude mcp list
claude mcp get uprank
```

### Codex

Register the server with the Codex CLI; the bearer header is read from the env var.

Config file: `~/.codex/config.toml`

```bash
codex mcp add uprank --url https://uprank.devino.ca/api/mcp --bearer-token-env-var UPRANK_MCP_TOKEN
```

Confirm: Run codex mcp list and check that uprank is among the configured servers. Inside the Codex TUI, /mcp shows the active MCP servers.

```bash
codex mcp list
```

### Cursor

Add the server to the global MCP config (or .cursor/mcp.json in a project).

Config file: `~/.cursor/mcp.json`

Merge this into the config file (create it if missing), keeping any existing servers:

```json
{
  "mcpServers": {
    "uprank": {
      "url": "https://uprank.devino.ca/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UPRANK_MCP_TOKEN}"
      }
    }
  }
}
```

Confirm: Open Customize in the sidebar and choose MCPs: uprank should be listed with its toggle on. Its tools also appear in the tools list at the top of the chat panel.

### Windsurf

Add the server to the Cascade MCP config.

On Windows the file is %APPDATA%\devin\mcp_config.json. Older Windsurf builds, before the rename to Devin Desktop, read ~/.codeium/windsurf/mcp_config.json instead.

Config file: `~/.config/devin/mcp_config.json`

Merge this into the config file (create it if missing), keeping any existing servers:

```json
{
  "mcpServers": {
    "uprank": {
      "serverUrl": "https://uprank.devino.ca/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UPRANK_MCP_TOKEN}"
      }
    }
  }
}
```

Confirm: Open the Actions (...) menu at the top right of the Cascade panel. Its MCPs section lists uprank with the number of tools it has enabled, and a toggle to switch it on or off.

### VS Code (Copilot)

Add an HTTP server entry to the workspace .vscode/mcp.json.

VS Code prompts for the token the first time the server starts.

Config file: `.vscode/mcp.json`

Merge this into the config file (create it if missing), keeping any existing servers:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "uprank-token",
      "description": "uprank MCP token",
      "password": true
    }
  ],
  "servers": {
    "uprank": {
      "type": "http",
      "url": "https://uprank.devino.ca/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:uprank-token}"
      }
    }
  }
}
```

Confirm: Run MCP: List Servers from the Command Palette and select uprank to start, stop or restart it, or to show its output. It is also listed under MCP SERVERS - INSTALLED in the Extensions view.

### OpenCode

Add a remote MCP entry to opencode.json.

Config file: `~/.config/opencode/opencode.json`

Merge this into the config file (create it if missing), keeping any existing servers:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "uprank": {
      "type": "remote",
      "url": "https://uprank.devino.ca/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:UPRANK_MCP_TOKEN}"
      },
      "enabled": true
    }
  }
}
```

Confirm: Run opencode mcp list: it lists every configured MCP server and its auth status, so uprank should appear there.

```bash
opencode mcp list
```

### Any other MCP-capable agent

Add a streamable-HTTP server named `uprank` that sends the header
`Authorization: Bearer <value of UPRANK_MCP_TOKEN>`. Use the agent's own env-var
interpolation if it has one (the example uses the common `${env:NAME}` form);
otherwise put the token only in a user-level config that is never committed.

```json
{
  "mcpServers": {
    "uprank": {
      "type": "http",
      "url": "https://uprank.devino.ca/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UPRANK_MCP_TOKEN}"
      }
    }
  }
}
```

## 3. Verify

Most agents load new MCP servers only after a restart, so verify over plain
HTTP first. This calls the `article_list` tool directly:

```bash
curl -sS -X POST https://uprank.devino.ca/api/mcp \
  -H "Authorization: Bearer $UPRANK_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"article_list","arguments":{"pageSize":1}}}'
```

Success is a JSON-RPC `result` whose content lists `items` and a
`nextCursor` (the list may be empty in a fresh workspace). An HTTP **401**
means the token is missing, revoked, expired, or named `dev:*` against
production — ask the user for a fresh token. A result with `isError: true` and
code `UNAUTHORIZED` means the credential lacks `article:read`.

After the agent restarts, `article_list` is also available as a native tool.

## 4. Completion message

Print this to the user, filled in:

- Installed: uprank MCP server (`https://uprank.devino.ca/api/mcp`) registered in <agent name>.
- Token: read from `UPRANK_MCP_TOKEN`.
- Verified: `article_list` over HTTP returned <n> article(s).
- Still to do by the user: restart or reload the agent if it does not pick up
  new MCP servers live (Claude Code: run `/mcp` to confirm the server shows as
  connected).
- A live publication request (`publication_publish`) needs a credential with
  `publication:live`, which is never granted by default, and the literal
  confirmation `confirm: "PUBLISH LIVE"`. It records the request in uprank
  and does not push anything to the CMS.

## Resources

- App: https://uprank.devino.ca
- Agent setup guides: https://uprank.devino.ca/agent-setup
- FAQ: https://uprank.devino.ca/faq
- Machine-readable index: https://uprank.devino.ca/llms.txt
- MCP endpoint: https://uprank.devino.ca/api/mcp
- Credentials: https://uprank.devino.ca/mcp
- Support: support@devino.ca