# Holocron MCP for Copilot

**Holocron** gives GitHub Copilot agents direct access to the legacy
documentation this portal publishes. Once it is set up, Copilot can search the
documentation, answer questions from it with citations, and look up valid filter
values without you leaving the editor and without running `legends search` or
`legends chat` yourself.

Holocron is a Model Context Protocol (MCP) server. You do not configure it by
hand: the `legends` CLI signs you in and registers it with your Copilot hosts in
two commands.

## What you get

Copilot sees five tools, all prefixed with `holocron_`:

| Tool | What it does | Speed |
| --- | --- | --- |
| `holocron_ask` | Writes an answer grounded in the documentation and lists the source documents it used. Supports follow-up questions. | Slow, up to a minute |
| `holocron_search_docs` | Returns a ranked list of matching documents with the best passage from each. Writes no answer. | A second or two |
| `holocron_get_doc` | Returns a whole document that `holocron_search_docs` found or `holocron_ask` cited. A large document comes back as an outline that Copilot reads section by section. | A second or two |
| `holocron_list_filter_values` | Lists the valid values for a filter: repositories, repository types, libraries, document types and reference types. | Under a second |
| `holocron_status` | Reports whether Holocron is connected and, if it is not, exactly what to do. | Instant, runs locally |

Holocron reads the same corpus as this portal and [Legends Chat](legends-chat.md).
A repository's code shows up in Holocron's results only after its documentation
has been [published to the portal](publishing-to-portal.md).

## How it works

```mermaid
graph LR
    A[Copilot agent] -->|stdio| B[legends agent mcp<br/>on your machine]
    B -->|your Entra token| C[Holocron]
    C -->|on your behalf| D[Legends AI]
    D --> E[(Published<br/>documentation)]
```

- Copilot starts `legends agent mcp`, a small MCP server built into the CLI you
  already have.
- That local server gets an Entra token for you silently and forwards each tool
  call to Holocron.
- Holocron calls Legends AI **as you**, so every request is checked against your
  business role and attributed to you.
- No credentials are written into any MCP configuration file.

## Before you start

- The [`legends` CLI is installed](install-cli.md), version **1.7 or later**.
- You hold the **`legends-chat-user`** business role. It is the same role
  [Legends Chat](legends-chat.md#access) uses, so if you can use Legends Chat you
  already have it.
- You use GitHub Copilot in at least one of **VS Code** (agent mode),
  **Copilot CLI**, the **GitHub Copilot app** or **Visual Studio**. Holocron is not available in Visual
  Studio run as administrator. See
  [Visual Studio run as administrator](#visual-studio-run-as-administrator).

Holocron works on Windows, macOS and Linux.

!!! note "Holocron does not use your API key"
    `legends login` stores the API key used by `legends search`, `legends chat`,
    `legends list` and the stored-procedure lookups doc gen runs. Holocron uses
    your own Entra sign-in instead, through `legends auth`. The two are
    independent. Setting up Holocron does not change how the API-key commands
    work, and you still need `legends login` for doc gen.

    | | `legends login` | `legends auth` |
    | --- | --- | --- |
    | Credential | API key from Keeper | Your Entra account |
    | Used by | `search`, `chat`, `list`, `oracle`, `sqlserver` | Holocron MCP tools only |
    | Platforms | Windows only | Windows, macOS, Linux |

## 1. Update the CLI

```powershell
legends update --install
legends --version          # 1.7.0 or later
```

## 2. Sign in

```powershell
legends auth generate
```

On Windows this shows the Windows account picker, and it is usually one click.
On macOS and Linux it opens your browser. The token is cached in your user
profile and refreshed silently, so you normally do this once per machine.

## 3. Register Holocron with Copilot

```powershell
legends agent init --dry-run   # optional: show what would change
legends agent init
```

`agent init` detects the Copilot hosts on your machine and registers the
`legends` MCP server with each one. It only changes **your user-level** settings,
never files in a repository, and running it again changes nothing. The one
repository file Holocron uses is written by `legends init`, the doc gen setup,
not by `agent init`. See [Coding in legacy repos](#coding-in-legacy-repos).

=== "VS Code"

    Copies the `legends` agent plugin to a stable folder in your profile and
    adds that folder to `chat.pluginLocations` in your user `settings.json`
    (VS Code and VS Code Insiders). The plugin contains the MCP server
    registration and a skill that teaches Copilot when to use each tool.

=== "Copilot CLI"

    Registers the same plugin folder as a local plugin marketplace named
    `legends` and enables `legends@legends` in `~/.copilot/settings.json`.
    Copilot CLI loads the plugin straight from that folder, so
    `copilot plugin list` shows it under **Live Plugins**.

    The GitHub Copilot app reads the same registration in
    `~/.copilot/settings.json`, so it needs no separate step.

=== "Visual Studio"

    Visual Studio does not support agent plugins, so `agent init` adds a
    `legends` server to `%USERPROFILE%\.mcp.json` instead.

| Option | Use it to |
| --- | --- |
| `--dry-run` | Print the planned changes without writing anything. |
| `--hosts vscode,copilot-cli,visualstudio` | Register with specific hosts instead of the detected ones. |
| `--env TEST` | Point the MCP server at the test environment. See [Environments](#environments). |
| `--grant-permissions` | Let Copilot run the read-only `legends search`, `legends chat` and `legends list` commands without asking each time. |
| `--refresh` | Re-copy the plugin without touching host settings. `legends update --install` runs this for you. |

!!! tip "Approving the Holocron tools"
    `--grant-permissions` covers terminal commands, not MCP tools. The first
    time Copilot calls a Holocron tool, your host asks for approval. All five
    tools are read-only, so choosing the host's **Always allow** for the
    `legends` server is safe.

## 4. Reload and check

| Host | What to do |
| --- | --- |
| VS Code | Reload the window once (**Developer: Reload Window**). |
| Copilot CLI | Start a new session. |
| GitHub Copilot app | Start a new session. Plugins load when a session starts, so existing sessions do not get the tools until you run `/mcp reload` in them. |
| Visual Studio | Restart Visual Studio. |

Then, in agent mode, ask Copilot:

```text
Use holocron to list the libraries.
```

Copilot should call `holocron_list_filter_values` and show library names with
counts. If it can see only `holocron_status`, ask it to call that tool and follow
the remedy it returns, or see [Troubleshooting](#troubleshooting).

Steps 2 and 3 can run in either order. If you register first and sign in later,
the tools appear within a minute, with no reload needed.

## Using Holocron

Copilot chooses the tool from your question. You can also name the tool in your
prompt.

Copilot also uses Holocron on its own during coding tasks in a legacy repo, when
the answer is outside the repo: how a shared library or framework behaves,
conventions in other apps, tables, stored procedures and business rules owned
elsewhere, and what depends on the app. You do not need to name it. See
[Coding in legacy repos](#coding-in-legacy-repos).

| You want | Copilot should use |
| --- | --- |
| An explanation: how something works, why, or what it is for | `holocron_ask` |
| To find where something is documented, or the exact wording of a rule | `holocron_search_docs` |
| To read a whole document that a search found or an answer cited | `holocron_get_doc` |
| The correct name of a library, repository or document type | `holocron_list_filter_values` |

Example prompts:

```text
Use holocron to explain how premium audit batches are scheduled.
Search holocron for the business rules documented in SAIF.Framework.BaseN.
Which libraries does holocron know about in the IT.BOF.Framework repository?
Add claim number validation to this form, matching how other legacy apps validate claim numbers.
```

### Reading a whole document

`holocron_get_doc` reads a document that `holocron_search_docs` found or
`holocron_ask` cited. A short document comes back whole. A large one (over about
12,000 characters) comes back as an outline of numbered sections, and Copilot
then reads the section it needs or pages through the document. You do not need
to manage this yourself.

If the document is republished while Copilot is reading it, the tool says so
and Copilot starts again from the outline. A document over 100,000 characters
can only be partly read this way. For the rest, ask a question with
`holocron_ask`.

### Filters

`holocron_ask`, `holocron_search_docs` and `holocron_list_filter_values` accept
the same filters: `repoType`, `repoName`, `library`, `docType` and
`referenceType`, plus `docgen: true`, which limits results to package
documentation the same way `legends chat --docgen` does.

`repoType` takes a repository's documentation type, such as `Framework`,
`Front End` or `Rest API`. [Supported repository types](supported-repo-types.md)
lists every type and the portal section each one is filed under.

!!! warning "Filters take the canonical name"
    Filters are exact matches. `library` takes `SAIF.Framework.Core`, never the
    folder slug `saif-framework-core`, the repository name or a NuGet package
    id. Copilot is told to check names with `holocron_list_filter_values` first.
    If a search returns nothing, a wrong filter value is the usual cause.

The filters behave differently on the two main tools:

- On `holocron_search_docs` they are **strict**. Every result matches.
- On `holocron_ask` they **steer** the search by default. The answer can draw
  on a document outside the filter, and Holocron marks those sources. Ask for a
  strict scope ("only use IT.BOF.Framework") and Copilot sets `strictFilter`,
  which keeps every source inside the filter.

### Follow-up questions

`holocron_ask` returns a `conversationId`. Copilot passes it back on a follow-up
question, so you can ask "and which tables does it use?" without repeating the
context. Conversations are private to you and expire after 30 days without use.

### Answers and citations

`holocron_ask` gives its answer first, then lists its top five sources, the ones
the answer cites first. If it retrieved more, it says how many it left out. Each
source links to its page on this portal, and Copilot can read any of them in
full with `holocron_get_doc`. Every `holocron_search_docs` result links to its
page as well.

When the indexed documentation may not cover the question, the answer includes
a **coverage note**.

!!! note "A coverage note means inconclusive, not no"
    The note means the documentation does not settle the question. It does not
    mean the feature, table or rule does not exist. Check the code before you
    conclude anything.

!!! warning "Answers are grounded, not authoritative"
    Holocron answers from documentation that was itself generated. Treat an
    answer the way you would treat the underlying document: useful, and worth
    checking against the source code before you act on it. Follow the
    citations.

## Coding in legacy repos

`legends init`, which sets a repository up for doc gen, also installs
`.github/instructions/holocron.instructions.md` into the repo. Copilot applies
it to every request in that repo (`applyTo: "**"`). It tells Copilot that this
is a legacy SAIF repo and to use Holocron while it implements, fixes or reviews
code whenever the answer is outside the repo, and to skip Holocron when the
repo's own code and docs answer.

The file adds a small amount of context, about 150 tokens, to every request in
the repo. You can edit it or delete it. Running `legends init` again restores
the shipped version and replaces any edits.

## Doc gen

The doc gen agents use Holocron automatically when its tools are available and
fall back to the `legends` CLI when they are not. Nothing changes in how you run
doc gen, and runs on a machine without Holocron keep working.

Doc gen still needs your API key from `legends login`, because stored-procedure
lookups (`legends oracle query`, `legends sqlserver query`) are not Holocron
tools.

## Environments

The MCP server follows the environment set by `legends env`. Holocron runs in
the same four environments as the CLI:

| `legends env` | Holocron environment |
| --- | --- |
| `PROD` (default) | production |
| `TEST` | test |
| `QA` | qa |
| `UAT` | uat |

To point Copilot at test while your terminal stays on `PROD`, pin only the MCP
server, and sign in for test:

```powershell
legends agent init --env TEST
legends auth generate --env TEST
```

Run `legends agent init` again without `--env` to switch back.

!!! note "Access outside production"
    In production, the `legends-chat-user` role is assigned automatically from
    your job title. In test, qa and uat it comes from the same non-production
    group Legends Chat uses. If Holocron reports `forbidden` there, ask the
    Legends team.

## Keeping it current

`legends update --install` refreshes the plugin as part of the update. Holocron
runs from its own copy of the CLI under `%LOCALAPPDATA%\Legends\runtime`, so
the update does not need to stop it. Copilot sessions that are already open keep
working on the previous version, and new sessions use the new one. To move an
open session to the new version, reload it as in [step 4](#4-reload-and-check),
or run `/mcp reload` in Copilot CLI or the GitHub Copilot app.

If a host still starts Holocron through the `legends` command itself, from an
earlier preview or because `agent init` could not copy the CLI, the update stops
those Holocron servers so it can replace the CLI. The next `legends` command
lists them and what to do in each host:

| Host | After the update stopped Holocron |
| --- | --- |
| VS Code | Nothing. The server restarts on the next tool call. |
| Copilot CLI and the GitHub Copilot app | The `holocron_` tools are gone until you run `/mcp reload`, `/restart` or start a new session. |
| Visual Studio | Reopen the solution. |

The update then moves your hosts to the runtime copy, so later updates leave
open sessions alone. If `agent init` warns that it could not copy the CLI, run
`legends agent init --refresh`.

If anything looks out of date, `legends agent init` is always safe to run again.

## Troubleshooting

Start by asking Copilot to **call `holocron_status`**. It reports the connection
state and the exact fix.

| `holocron_status` reports | What to do |
| --- | --- |
| `not_signed_in` | Run `legends auth generate`. The tools appear within a minute. |
| `unauthorized` | Run `legends auth clear`, then `legends auth generate`. |
| `unreachable` | Check your network or VPN connection. The server keeps retrying on its own. |
| `connected`, but a tool returns `forbidden` | You do not hold `legends-chat-user`. Request it as described in [Legends Chat](legends-chat.md#access). |

| Symptom | What to do |
| --- | --- |
| No `holocron_` tools at all, not even `holocron_status` | Check `legends --version` is 1.7 or later, run `legends agent init`, then reload the host. |
| `holocron_ask` returns `timeout` | Retry after a short wait, ask a narrower question, or ask Copilot to use `holocron_search_docs` instead. |
| A search returns nothing | Check the filter values with `holocron_list_filter_values`. |
| Copilot worked on a legacy repo without using Holocron | Run `legends init` in the repo so `.github/instructions/holocron.instructions.md` is there, then start a new session. Or ask Copilot to use holocron. |
| Sign-in asks for consent or fails with an `AADSTS` error | Contact the Legends team. |
| You want to sign out | `legends auth clear`. |

### Visual Studio run as administrator

Debugging a legacy IIS-hosted application locally needs Visual Studio run as
administrator, under your separate admin account. Holocron is not available in
that session:

- `legends agent init` registers Holocron in the profile of the account that
  runs it, and the server it registers is the `legends` CLI installed for that
  account.
- The CLI is installed from the SAIF Azure DevOps feed. Your admin account has
  no Azure DevOps access, so the CLI cannot be installed under it.
- Visual Studio run as administrator reads the admin account's profile, which
  has no `legends` server.

Split the work instead:

1. Make your changes with Holocron in VS Code, Copilot CLI or the GitHub
   Copilot app, under your normal account.
2. When you need to debug locally, open the solution in a separate Visual
   Studio instance run as administrator. Holocron is not available there.

## Turning it off

| Host | How |
| --- | --- |
| VS Code | Disable the `legends` server in the MCP server list, or remove the plugin folder from `chat.pluginLocations` in your user settings. |
| Copilot CLI | `copilot plugin disable legends@legends`. Running `legends agent init` again does not turn it back on. |
| GitHub Copilot app | The same as Copilot CLI. The app reads the same setting. |
| Visual Studio | Remove the `legends` entry from `%USERPROFILE%\.mcp.json`. |

Run `legends auth clear` to remove the cached token as well.

## Related

- [Install / update the CLI](install-cli.md): installing the CLI that hosts
  Holocron's local server.
- [Legends Chat](legends-chat.md): the same corpus, in a browser.
- [Quick start](quick-start.md): a full doc gen run. Doc gen uses Holocron when
  it is set up.