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:
github-actions[bot]
2026-05-08 12:26:48 +10:00
committed by GitHub
parent a4ca380b7c
commit 93acc6c6eb
3 changed files with 61 additions and 5 deletions
@@ -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