mirror of
https://github.com/github/awesome-copilot.git
synced 2026-05-15 19:21:45 +00:00
docs: update Learning Hub with CLI v1.0.42-1.0.43 features (#1648)
- understanding-mcp-servers.md: add Troubleshooting section with MCP stderr diagnostics (v1.0.42+) and /mcp show usage guidance - copilot-configuration-basics.md: document -C startup flag (v1.0.42+), Auto mode server-side model routing (v1.0.43+), and /statusline username toggle (v1.0.43+) - agents-and-subagents.md: add rubber-duck agent experimental feature documentation (v1.0.42+) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
committed by
GitHub
parent
a4ca380b7c
commit
93acc6c6eb
@@ -3,7 +3,7 @@ title: 'Understanding MCP Servers'
|
||||
description: 'Learn how Model Context Protocol servers extend GitHub Copilot with access to external tools, databases, and APIs.'
|
||||
authors:
|
||||
- GitHub Copilot Learning Hub Team
|
||||
lastUpdated: 2026-05-01
|
||||
lastUpdated: 2026-05-07
|
||||
estimatedReadingTime: '8 minutes'
|
||||
tags:
|
||||
- mcp
|
||||
@@ -261,13 +261,43 @@ If your team has internal tools or proprietary APIs, you can build custom MCP se
|
||||
|
||||
MCP server SDKs are available in [Python](https://github.com/modelcontextprotocol/python-sdk), [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk), and other languages. Browse the [Agents Directory](../../agents/) for examples of agents built around MCP server expertise.
|
||||
|
||||
## Troubleshooting MCP Connection Issues
|
||||
|
||||
When an MCP server fails to start or loses its connection, Copilot CLI surfaces a warning with actionable details to help you diagnose the problem quickly.
|
||||
|
||||
**Failure warnings include stderr output** (v1.0.42+): If your MCP server prints error messages to stderr (e.g., missing environment variables, connection refused, import errors), those messages are now included directly in the CLI warning. This means you usually see the root cause without needing to run the server manually.
|
||||
|
||||
For example, a PostgreSQL server that can't connect because `DATABASE_URL` is not set will show:
|
||||
|
||||
```
|
||||
⚠ MCP server "postgres" failed to start
|
||||
Error: connect ECONNREFUSED 127.0.0.1:5432
|
||||
stderr: Error: DATABASE_URL environment variable is required
|
||||
```
|
||||
|
||||
**Diagnosing connection problems with `/mcp show`**: Run `/mcp show` to see the current status of all configured MCP servers — which ones are running, which have failed, and their connection details. When an MCP server name contains whitespace, the failure warning also suggests a directly runnable `/mcp show <name>` command for quick inspection.
|
||||
|
||||
```
|
||||
/mcp show # list all servers and their status
|
||||
/mcp show postgres # inspect a specific server
|
||||
```
|
||||
|
||||
**Common causes and fixes**:
|
||||
|
||||
| Symptom | Likely Cause | Fix |
|
||||
|---------|--------------|-----|
|
||||
| `ENOENT` on startup | Missing `npx` / `python` / command | Verify the executable is installed and in your PATH |
|
||||
| Auth errors / 401 | Expired or missing API key | Update the `env` field in your config; check `/mcp auth` |
|
||||
| Server starts then exits | Server crash | Check stderr output in the warning for the root cause |
|
||||
| Server blocked | Organization policy | Contact your admin; switch to an approved server |
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Principle of least privilege**: Only give MCP servers the minimum access they need. Use read-only database connections for analysis agents.
|
||||
- **Keep secrets out of config files**: Use `${input:variableName}` for API keys and connection strings, or load from environment variables.
|
||||
- **Document your servers**: Add comments or a README explaining which MCP servers your project uses and why.
|
||||
- **Version control carefully**: Commit `.mcp.json` or `.vscode/mcp.json` for shared server configurations, but use `.gitignore` for any files containing credentials.
|
||||
- **Test server connectivity**: Verify MCP servers start correctly before relying on them in agent workflows.
|
||||
- **Test server connectivity**: Verify MCP servers start correctly before relying on them in agent workflows. Use `/mcp show` to check status and read stderr output in any failure warnings.
|
||||
- **Use the MCP allowlist (experimental)**: In high-security environments, the `MCP_ALLOWLIST` feature flag lets you validate MCP servers against a configured registry, blocking unrecognized servers from loading. MCP servers that are blocked by the allowlist policy are **hidden from `/mcp show`** to avoid confusion — only permitted servers appear in that view. This is an experimental feature for enterprise environments requiring strict control over which MCP servers are permitted.
|
||||
|
||||
### Organization Policy for Third-Party MCP Servers
|
||||
|
||||
Reference in New Issue
Block a user