Practical examples

Example 1: GitHub workflow automation

You: Help me push the current changes to GitHub, then create a PR titled "Add new feature"

Claude:
1. Check current git status...
2. Create a new branch feature/new-feature...
3. Commit changes...
4. Push to remote...
5. Call github_create_pull_request to create the PR...
6. PR created: https://github.com/owner/repo/pull/123

Example 2: Database query

You: Query the 10 most recently registered users in the database

Claude:
1. Connect to the SQLite database...
2. Execute query: SELECT * FROM users ORDER BY created_at DESC LIMIT 10
3. Return results:
   - Zhang San (zhang@example.com) - 2025-02-28
   - Li Si (li@example.com) - 2025-02-27
   ...

Example 3: Webpage screenshot analysis

You: Open https://example.com, take a screenshot, and analyze the page design

Claude:
1. Launch browser...
2. Navigate to https://example.com...
3. Capture screenshot...
4. [Returns screenshot]
5. Page design analysis:
   - The layout uses a centered design with a max width of 1200px
   - The main color is blue (#3b82f6)
   - The navigation bar is fixed to the top
   ...

Example 4: Integration with Notion

You: Save the notes I just wrote to Notion

Claude:
1. Use the Notion MCP server...
2. Create a new page...
3. Saved: https://notion.so/page/xxx

Debugging tips

Diagnose with natural language

When something goes wrong, just tell Claude Code directly:

You: My MCP server cannot connect. Please check it for me

You: The GitHub MCP tool call failed. What is the reason?

You: Why does the sqlite server always show "connecting"?

Claude Code will automatically:

1. Check the configuration file format
2. Validate environment variables
3. Test the server connection
4. Provide concrete fix suggestions

Common problem troubleshooting

Manual diagnostic command

/doctor

Example output:

System Diagnostic Report:
===============

Claude Code: v2.5.0 ✓
Node.js: v20.0.0 ✓

MCP server status:
• github: ✓ Connected (12 tools)
• sqlite: ✗ Connection failed - Database file not found
• puppeteer: ✓ Connected (8 tools)

Suggestions:
1. Check whether the sqlite database path is correct
2. Make sure the .claude/mcp.json format is correct

Best practices

1. Prefer project-level configuration

Why recommend project-level configuration?

Different projects often need different MCP services. For example, a frontend project may need browser testing tools, while a backend project may need database connections. With project-level configuration, each project can have its own dedicated set of MCP servers, avoiding the chaos of one large global config.

More importantly, project-level config can be committed to Git. After team members clone the project, they can directly use the same MCP services without reconfiguring everything.

Project A, frontend project -> .claude/mcp.json contains browser testing MCP
Project B, backend project -> .claude/mcp.json contains database MCP

2. Store sensitive information in environment variables

Never hard-code secrets in the configuration file.

Configuration files may be accidentally committed to Git and leak keys. The correct approach is to store sensitive values in environment variables and only reference the variable names from the config file. That way, even if the config file becomes public, the real secrets are still hidden.

{
  "env": {
    "GITHUB_TOKEN": "$GITHUB_TOKEN",
    "GITHUB_TOKEN": "ghp_abc123"
  }
}

The first form is good because it reads from the environment variable. The second form is bad because it hard-codes a secret directly.

3. Pin versions

Why do you need to pin versions?

By default, npx -y will always use the latest version of an MCP server. This can cause problems: a new version may introduce breaking changes, or a package may suddenly be removed or renamed.

By appending @version to the package name, you ensure that a validated version is always used, reducing surprises caused by automatic upgrades.

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github@1.2.3"]
}

4. Document your MCP configuration

Help teammates understand the MCP setup quickly

When a project includes multiple MCP servers, new team members may not understand what each server is for or what configuration it requires. Creating a README.md under the .claude/ directory that explains each server's purpose, required config, and how to obtain credentials can significantly reduce communication cost.

Create .claude/README.md in your project:

# MCP Configuration Notes

MCP servers used in this project:

## github
Used for GitHub automation. Requires GITHUB_TOKEN.

## sqlite
Connects to ./data/app.db for querying and modifying data.

## puppeteer
Used for E2E testing.

Claude Code vs Claude Desktop