# Choose the right GitHub Projects board in Gitsu MCP

Author: Sahil Dave
Canonical: https://gitsu.app/docs/gitsu-mcp-board-selection
Published: 2026-10-07
Updated: 2026-10-07
Last checked: 2026-10-07

> **TL;DR** Pass project_id to select a GitHub Projects board explicitly in Gitsu MCP. Without it, Gitsu uses the agent workspace, its origin git remote and the repository-linked boards. If several boards are linked, the open board breaks the tie, then the most recently opened one; otherwise the tool asks the caller to choose. Every answer names the board. A read outside a git checkout can use the live open board, but a write cannot use that fallback.

Gitsu MCP board selection determines which GitHub Projects board an agent reads or changes. Pass `project_id` to select the board explicitly; otherwise Gitsu discovers it from the agent's workspace and names the selected board in its answer.

That headline is worth checking before acting on a list of tickets. A complete answer from the wrong board still gives the agent the wrong work.

## How do I select a specific board?

Pass the board's actual `project_id` in the tool arguments to override automatic selection.

For example, the following `list_items` arguments select a board and filter its Priority column:

```json
{
  "project_id": "REPLACE_WITH_ACTUAL_PROJECT_ID",
  "fields": { "Priority": "P0" }
}
```

The string is a placeholder, not a usable project ID. Ask the agent to call `list_projects` to list accessible boards with their IDs, owners and URLs, then choose the entry whose URL matches the intended board. `list_projects` reads GitHub, so it does not share the cached board-list timing described on the [local reads page](/features/mcp-local-reads).

The project listing can be incomplete: it reads the first page of each source and reports when a full page leaves more to fetch. An absent entry is therefore not proof that the board does not exist or is inaccessible.

Use the same explicit project ID for subsequent reads and writes when the task must stay on one board. If several repositories contribute items with the same issue number, include the repository when identifying an item.

## How does Gitsu choose a board when project_id is omitted?

Gitsu resolves the agent's working directory to a GitHub repository, then looks for Projects boards linked to that repository.

The documented discovery sequence is:

1. Use the MCP client's workspace roots when supported, or the sidecar process's working directory otherwise.
2. Read that directory's `origin` git remote and resolve its GitHub owner and repository.
3. Look up the boards linked to that repository.
4. Use the single linked board, or apply the tie-breaking rules when several are linked.

This makes the folder where the agent runs part of the answer. Opening a board in Gitsu does not ordinarily erase the agent's repository context. An explicit project ID also reaches a board linked to no repository, which repository discovery cannot find.

## Which board wins when the repository has several projects?

The linked board open in Gitsu wins first, followed by the most recently opened linked board; without either, the tool lists the choices.

| Situation | Selection |
| --- | --- |
| Explicit `project_id` supplied | The named board |
| Exactly one repository-linked board | That board |
| Several linked boards and one is open | The open linked board |
| Several linked boards, no open match, but a recent match exists | The most recently opened linked board |
| Several linked boards with no open or recent match | The caller chooses from the listed boards |

The answer names the selected board and lists alternatives when resolving several linked boards. The open-board preference breaks a tie within the repository's linked boards; an unrelated open board does not win that tie.

## What happens outside a git checkout?

A read can fall back to the board currently open in the running app when its directory is not a git checkout, but a write cannot use that fallback.

The read answer explains that no git remote was available, names the board used, and points to `project_id` as the override. With Gitsu closed, a saved snapshot's old open-board value is insufficient for this fallback, so the caller must name the board explicitly.

A checkout with an unparseable remote, a remote named something other than `origin`, or missing `git` has a setup error to resolve. Those cases retain the error rather than silently using an unrelated board.

The stricter write rule exists because a write changes shared data. Without a resolvable repository or an explicit project ID, the agent must specify the destination before making that change.

## How do I correct an answer from the wrong board?

Select the intended board by ID and repeat the read before using its result.

1. Read the board title and URL at the top of the current answer.
2. Call `list_projects` and identify the intended board by its URL and owner.
3. Repeat the original tool call with that board's `project_id`.
4. Verify the new answer names the intended board, then continue the task with that explicit ID.

The [MCP setup guide](/guides/connect-claude-code-to-github-projects-mcp) covers registration. The [server reference](/features/mcp-server) explains the read and write tools; the [priority filter reference](/docs/gitsu-mcp-priority-filters) helps check that a correctly selected board is being queried with its own vocabulary.

## How we checked

Gitsu's workspace-to-repository discovery, explicit project override, linked-board tie-breaking and separate read/write rules outside a checkout, traced to the sidecar reference and tests.

## Frequently asked questions

### How do I make Gitsu MCP use a specific board?

Pass the board's actual project_id in the tool arguments. An explicit project_id overrides automatic discovery.

### Does Gitsu MCP always use the board open in the app?

No. In a repository, the open board breaks a tie among the boards linked to that repository. It does not replace the repository context with an unrelated board.

### Can Gitsu MCP read a board outside a git checkout?

A read from a folder that is not a git checkout can use the board currently open in the running app. With the app closed, pass project_id. Writes do not use this read fallback.

### Can Gitsu MCP discover a board linked to no repository?

Not through repository-based discovery. Select that board by its project_id instead.

## Related resources

- [Connect Claude Code to GitHub Projects with MCP](https://gitsu.app/guides/connect-claude-code-to-github-projects-mcp)
- [The Gitsu MCP server for GitHub Projects v2](https://gitsu.app/features/mcp-server)
- [Gitsu MCP priority filters: find P0 items](https://gitsu.app/docs/gitsu-mcp-priority-filters)
- [How fresh is Gitsu MCP data? Cached vs fresh reads](https://gitsu.app/docs/gitsu-mcp-cache-freshness)