---
icon: lucide/bot
---

# Copilot MCP Mechanics

## Purpose

This page explains how GitHub Copilot in VS Code consumes native skill resources from `personal-mcp`, including sessions where tools are visible but resource attachment is not.

## Capability Lanes

Copilot interacts with MCP servers through independently exposed lanes:

1. tools invoked during execution
2. resources attached as read-only context
3. server-provided prompts

This server publishes skills as native `skill://` resources, prompts through registry-backed resources and MCP prompt objects, and generic resource fallback tools through FastMCP.

## Native Skill Resources

For every skill, Copilot can discover:

1. `skill://<name>/SKILL.md`
2. `skill://<name>/_manifest`
3. `skill://<name>/{path*}` supporting-file template

The main resource description comes from `SKILL.md`. The manifest discloses supporting paths, sizes, and SHA256 hashes. This is the only skill discovery contract; there is no parallel skill catalog.

## Resource Picker Availability

`MCP Resources...` in Add Context requires both:

1. a connected server advertising resource capability
2. a chat surface that exposes MCP resource attachment

A successful `resources/list` response does not guarantee the picker appears in every session type. Use `MCP: Browse Resources` to distinguish server availability from chat UI availability.

## Recommended Workflow

When resource attachment is available:

1. browse the server's resources
2. attach one relevant `skill://<name>/SKILL.md`
3. attach `_manifest` only if supporting detail may be needed
4. attach only selected supporting files

When only tools are available:

1. call `list_resources`
2. select a native main skill URI by name and description
3. call `read_resource` for that URI
4. read `_manifest` and supporting files only as needed

Both paths resolve through the same FastMCP provider.

## Prompt Examples

Resource attachment:

```text
Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.
```

Tool-only discovery:

```text
Call list_resources, choose the best matching skill://.../SKILL.md resource, and read it. Inspect its _manifest only if a supporting file is needed. Load at most two candidate skills.
```

Direct loading:

```text
Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.
```

Supporting material:

```text
Read skill://pytesting/_manifest, select the one reference relevant to async test lifecycle, and use that file with the main skill instructions.
```

## Repository Instruction Pattern

A repo-level instruction should name the native retrieval order and context budget:

```md
When a task matches a personal-mcp skill:

1. Prefer an already attached native skill resource.
2. Otherwise use `list_resources` and select one `skill://<name>/SKILL.md` resource by description.
3. Read `_manifest` only when supporting material is needed.
4. Load at most two candidate main files and only the relevant supporting paths.
5. Reconcile guidance with the current repository before editing.
```

Instructions steer behavior but do not force VS Code to attach resources automatically.

## Prompt Objects

Prompt modules remain separate from skills. When the client supports MCP prompt APIs, use prompt listing and `get_prompt` for parameterized workflows. Authored `PROMPT.md` remains the source of truth for each prompt.

## Troubleshooting

1. Use `MCP: List Servers` to confirm the server is enabled.
2. Use `MCP: Browse Resources` to confirm native skill resources exist.
3. Restart the MCP server after changing skill files because production uses `reload=False`.
4. Reload the VS Code window if the server is healthy but the resource picker remains stale.
5. In tool-only sessions, verify `list_resources` and `read_resource` are visible.

## Further Reading

1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
2. [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
3. [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
4. [Manage context for AI](https://code.visualstudio.com/docs/chat/copilot-chat-context)
5. [Skill Usage Mechanics](./usage.md)