prompts/docs/copilot.md

icon

icon
lucide/bot

Copilot MCP Mechanics

Purpose

This page explains how the GitHub Copilot extension in VS Code behaves as an MCP client when connected to personal-mcp, including why tools can appear while resource attachment appears unavailable.

Core Model

Copilot interacts with MCP servers through separate capability lanes:

1. tools (invoked by the model during execution)
2. resources (attached as read-only context)
3. prompts (server-provided prompt templates)

These lanes are related but independently gated in the client.

Reliable paths are:

1. attach MCP resources explicitly through Add Context > MCP Resources or MCP: Browse Resources
2. let Copilot invoke MCP tools when the task and tool descriptions make that relevant
3. invoke MCP prompts explicitly with /server.prompt when your server exposes them

What Actually Happens In VS Code

MCP server side

Your server can advertise resources and serve them correctly. In this project that includes catalog resources and skill document resources.

Copilot session side

The chat surface exposes tools, resources, and prompts through different UI paths. In practice, you can encounter sessions where tool use is available but MCP resource attachment is not exposed in Add Context.

That is why you can sometimes see MCP tools before you see Add Context > MCP Resources.

Why The Picker Sometimes Shows Only Tools

MCP Resources... in Add Context requires at least:

1. at least one connected MCP server advertises resource capability
2. the current chat surface exposes MCP resource attachment

If the second condition is not met, resources can be available on the server while still being absent from the picker.

Practical Workflow

Use this sequence to confirm behavior:

1. run MCP: Browse Resources and verify resources exist
2. use MCP: List Servers to verify the server is enabled and running
3. open Copilot Chat
4. check Add Context for MCP Resources...
5. if still missing, restart the server and reload VS Code window

Recommended Usage Pattern

1. rely on canonical catalog resources for discovery (skills_index, then skills/{skill_id})
2. fetch only selected skill documents for context
3. keep slash commands for deterministic fallback flows

When resource attachment is unavailable in the active session, use thin catalog discovery tools as operational fallback:

1. search_patterns
2. get_pattern_by_id
3. get_skill_document_by_id

These should stay read-only, minimal, and schema-aligned with catalog resources.

What To Type In Copilot Chat

Use prompts that tell Copilot which MCP feature path to take.

If MCP Resources... is available

Use the resource attachment UI first, then ask Copilot to work from the attached material.

Example:

I attached the catalog resources and the FastAPI async SQLAlchemy modernization skill document. Use that context to propose a migration plan for this repo.

If you want to keep the attachment sequence explicit, use:

I attached personal-mcp catalog resources first. Use them to identify the best matching skill, then work only from the selected skill document.

If only tools are available

Ask Copilot to explicitly use the catalog tools.

Example discovery prompt:

Use the personal-mcp catalog tools to search for the most relevant skill for FastAPI async SQLAlchemy modernization. Then load the selected skill document and use it as context for your answer.

Example direct-load prompt:

Call get_skill_document_by_id for fastapi-async-sqlalchemy-modernization and use that document as the main context for this task.

Example bounded-selection prompt:

Search personal-mcp skills for NiceGUI UI customization, select at most 2 strong matches, load the best skill document, and answer using only that material plus the workspace code.

Repo Instructions Example

Repo instructions are the best place to teach Copilot when MCP content is relevant and which path to prefer.

If you add a repo-level copilot-instructions.md, keep the rule simple: prefer catalog-first discovery, keep loaded skill context small, and fall back to tools when resource attachment is unavailable.

Instructions can strongly steer behavior, but they do not guarantee that VS Code will auto-attach MCP resources for a request. For reliable resource use, either attach resources explicitly or prompt Copilot to use the fallback tools.

Example:

# MCP Usage

When a task may benefit from personal-mcp skills, use this sequence:

1. Start with personal-mcp catalog discovery when the task appears to match documented implementation patterns.
2. Prefer MCP resources when the chat surface exposes resource attachment.
3. If MCP resource attachment is unavailable, use catalog tools instead.
4. Load only the most relevant skill document or at most 2 skill documents.
5. Treat skill documents as guidance, then reconcile them with the actual repository code before making changes.

Preferred discovery order:

1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed

Tool fallback order:

1. `search_patterns`
2. `get_pattern_by_id`
3. `get_skill_document_by_id`

If confidence is low after catalog discovery, ask one clarifying question before loading more skill documents.

That instruction style does two useful things:

1. it tells Copilot to prefer the MCP server when relevant without forcing it on every prompt
2. it keeps context size bounded so skill loading does not become noisy or expensive

If you want stronger behavior, add one more line that names the MCP server directly:

Use the `personal-mcp` server for skill discovery whenever the task involves documented implementation patterns available from the catalog.

Known Gotcha

A successful resources/list response from the server does not guarantee the resource picker appears in every Copilot session type. UI availability is session-capability-dependent.

Further Reading

VS Code docs

1. Add and manage MCP servers
2. MCP configuration reference
3. Manage context for AI
4. AI features cheat sheet

Project docs

1. Resource-First Pattern Module Architecture
2. Static Docs Hosting Pattern
3. Skill Usage Mechanics