Skip to content

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. A repository's code shows up in Holocron's results only after its documentation has been published to the portal.

How it works

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, version 1.7 or later.
  • You hold the legends-chat-user business role. It is the same role Legends Chat 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.

Holocron works on Windows, macOS and Linux.

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

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

2. Sign in

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

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.

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.

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 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.
--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.

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:

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.

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.

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:

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 lists every type and the portal section each one is filed under.

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.

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.

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:

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

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

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, 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.
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.