# MCP reference

LogiKFlow's MCP server lets an agent read a pull request and save its reading order.

| | |
|---|---|
| Endpoint | `https://logikflow.yemzikk.in/mcp` |
| Transport | Streamable HTTP (stateless, JSON responses) |
| Authorization | OAuth 2.1 with PKCE; scope `reviews` |
| Server name | `logikflow` |

## Tools

### get_ordering_guide

Returns the [ordering guide](/docs/ordering-guide) as Markdown. Call it once before saving an order. It takes no input and is read-only.

### get_pull_request

Returns a pull request's changed files, the saved order and its version, whether you may change the order, and the review link. Read-only.

| Input | Type | Required | Description |
|---|---|---|---|
| `owner` | string | yes | Repository owner, for example `acme` |
| `repo` | string | yes | Repository name, for example `app` |
| `number` | integer | yes | Pull request number |
| `include_patches` | boolean | no | Include each file's diff. Default `false`. Each file is capped at 20,000 characters and the response at 400,000. |

Result (JSON text):

```json
{
  "reviewUrl": "https://logikflow.yemzikk.in/r/acme/app/pull/123",
  "repository": "acme/app",
  "pullRequest": {
    "number": 123, "title": "Add grouped clipboard", "state": "open",
    "author": "octo", "base": "develop", "head": "clipboard-new", "headSha": "9fce14f", "url": "https://github.com/acme/app/pull/123"
  },
  "canArrange": true,
  "filesTruncatedByGitHub": false,
  "files": [
    { "path": "app/src/main/java/.../ClipboardStorage.kt", "status": "modified", "additions": 79, "deletions": 10 }
  ],
  "currentOrder": null,
  "baseVersion": 0
}
```

`currentOrder`, when an order exists, has `version`, `updatedBy`, `source` (`web` or `agent`), `savedBeforeLatestCommits` (true when commits were pushed after it was saved) and `sections` in the same shape `save_reading_order` takes. `status` is GitHub's: `added`, `removed`, `modified`, `renamed`, `copied`, `changed` or `unchanged`. Renamed files also have `previousPath`.

### save_reading_order

Saves the reading order, replacing the current one. Earlier versions stay in history. Requires write access to the repository.

| Input | Type | Required | Description |
|---|---|---|---|
| `owner` | string | yes | Repository owner |
| `repo` | string | yes | Repository name |
| `number` | integer | yes | Pull request number |
| `base_version` | integer | yes | `baseVersion` from `get_pull_request`; `0` when no order exists |
| `sections` | array | yes | 1 to 50 sections, in reading order |

Each section:

| Field | Type | Description |
|---|---|---|
| `title` | string, optional | Up to 200 characters. Omit only for a single untitled group in a tiny pull request. |
| `note` | string, optional | Up to 4,000 characters. Backticks render as code. |
| `checks` | string[], optional | Up to 20 checklist items, each up to 300 characters |
| `files` | array | Files in reading order: `{ "path", "note"?, "checks"?, "focus"? }` with the same limits. `focus` is `key`, `skim` or `generated`. |

Example input:

```json
{
  "owner": "acme", "repo": "app", "number": 123, "base_version": 0,
  "sections": [
    {
      "title": "Feature flag and analytics",
      "note": "Everything new is behind `enable_new_clipboard_experience`, off by default.",
      "checks": ["With the flag off, the clipboard page is unchanged"],
      "files": [{ "path": "app/src/main/java/.../RemoteConfigs.kt" }]
    },
    {
      "title": "Grouping model",
      "files": [
        { "path": "app/src/main/java/.../ClipboardListItem.kt" },
        { "path": "app/src/main/java/.../ClipExtractionUtils.kt", "note": "Clips with time 0 are never grouped.", "focus": "key" }
      ]
    }
  ]
}
```

Result:

```json
{ "saved": true, "version": 1, "reviewUrl": "https://logikflow.yemzikk.in/r/acme/app/pull/123", "sections": 2, "files": 3, "checklistItems": 1 }
```

A checklist item with the same text in the same section or file keeps its identity across saves, so reviewers' ticks survive a re-arrange.

## Errors

Tool errors come back as a result with `isError: true` and a message the agent can act on. Nothing is saved when a save fails.

| Situation | Message starts with |
|---|---|
| A changed file is missing, unknown or listed twice | The order must list every changed file exactly once |
| Someone saved a newer version | Conflict: … saved version N |
| No write access | … doesn't have write access |
| Invalid input, such as an empty checklist item | The order is invalid |
| Pull request not visible | GitHub says this pull request doesn't exist or this account can't see it |
| GitHub token expired or revoked | GitHub access for this connection has expired |
| GitHub rate limit | GitHub's rate limit was reached |

## Authorization

LogiKFlow follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization).

| Endpoint | Path |
|---|---|
| Protected resource metadata | `/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata | `/.well-known/oauth-authorization-server` |
| Authorization (consent page) | `/authorize` |
| Token | `/oauth/token` |
| Dynamic client registration | `/oauth/register` |

Client ID metadata documents are also accepted. Unauthenticated requests to `/mcp` get `401` with a `WWW-Authenticate` challenge.

- **Access tokens** last up to one hour and are refreshed automatically.
- **Refresh tokens** last 30 days from last use and at most 180 days.
- **Rate limit:** 120 MCP requests per minute per person.