# MCP: example scenario

A read-only GitHub MCP server lets the agent read an issue, its acceptance criteria and its comments itself instead of from text you paste.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/mcp/example-scenario

## Scenario

In `ticket-service`, work is tracked in GitHub Issues, and each issue lists acceptance criteria. Today you copy the issue text into the chat by hand. Details and later comments get lost on the way, and the agent cannot check which criteria its change meets, because it never saw the issue itself.

This page shows one way to fix that: connect GitHub's MCP server, limited to reading issues, so the agent fetches the issue on its own.

## Before → after

| | Before | After |
|---|---|---|
| Accuracy | The agent works from your paste, missing later comments | It reads the issue as it is now, comments included |
| Verification | No way to check the result against the criteria | The agent compares its result with each criterion |
| Effort | You copy and paste for every issue | You say "Implement issue #42" |
| Access | No tracker access; you decide what to paste | A token that can only read issues, kept out of the repo |

## Design

**Diagram:** The token lives in an environment variable outside the repo; the github server uses it to read issues and nothing else.

- Developer machine:
  - Agent + harness — MCP client, permission checks
  - GITHUB_MCP_TOKEN — environment variable, not in repo
- → MCP over HTTP
- github server — read-only, issues only
- → API call
- GitHub Issues — body, criteria, comments

Generic configuration, committed to the repo and scoped to the project (syntax and file name differ per agent):

```text
# generic
server name:  github
type:         remote (HTTP)
url:          <URL of GitHub's MCP server>
auth header:  Authorization: Bearer ${GITHUB_MCP_TOKEN}  (read from env var)
access:       read-only, issues toolset only
```

The file holds the variable's name, never its value. Each developer sets `GITHUB_MCP_TOKEN` in their own shell; a name of your own avoids clashing with variables that agents or CI already use. Some agents also ship a GitHub server built in; the agent pages show what yours does.

## What happens at runtime

<steps>

<step title="Session starts">

The harness reads the project configuration, connects to the `github` server and authenticates with the token from the environment.

</step>

<step title="Tool list is offered">

The server advertises its issue tools. Their names and schemas go to the model next to the built-in tools.

</step>

<step title="Model calls the issue tool">

You type "Implement issue #42". The model decides to call the server's issue-reading tool with the number 42.

</step>

<step title="Harness checks permission">

The normal permission rules apply to this call, as to any tool. Depending on your settings, you approve it or it is already allowed.

</step>

<step title="Server fetches">

The server calls GitHub with your token and returns the title, the body with its acceptance criteria, and the comments. That text enters the context.

</step>

<step title="Model works and checks">

The model changes code and tests, then goes through the criteria one by one and reports which it met.

</step>

</steps>

## What can go wrong

| Failure | How you notice | What to do |
|---|---|---|
| Issue text is untrusted input: a malicious issue or comment carries instructions (prompt injection) | The agent does something the task never asked for, such as fetching unrelated data | Treat issue text as data, keep the server read-only, and see the [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) |
| The token has too broad a scope | The token could write to repos or read private ones beyond this project | Use a fine-grained token limited to this repository's issues, read access only |
| Too many tools cost context | Turns get slower and costlier; the tool list is long | Enable only the issues toolset, not the whole server |
| Server unreachable or the token expired | The agent says the tool is missing, or calls fail with an authorization error | Check the network and the variable; renew the token and restart the session |
| Write tools enabled by accident | The agent comments on or closes an issue | Turn on read-only mode, and deny write tools in the permission settings |