Skip to content

Commit a291aba

Browse files
sentrivanasentrivana
authored
Merge pull request #3 from getsentry/constantinius/feat/mcp-integration
feat: mcp-integration
2 parents c0f20a8 + b9b6ce1 commit a291aba

9 files changed

Lines changed: 2480 additions & 0 deletions

File tree

‎test-mcp/README.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# MCP Server Examples with Sentry Integration
2+
3+
This directory contains example [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers with Sentry integration, demonstrating three different API approaches: the standalone FastMCP library, the built-in MCP FastMCP module, and the low-level MCP API.
4+
5+
## 📚 About MCP
6+
7+
The [Model Context Protocol](https://github.com/modelcontextprotocol) is an open protocol that enables seamless integration between LLM applications and external data sources and tools.
8+
9+
## Examples
10+
11+
### 1. FastMCP Library Server (`main_fastmcp.py`)
12+
13+
Uses the standalone [`fastmcp`](https://github.com/jlowin/fastmcp) library - the most modern and feature-rich approach with HTTP support.
14+
15+
**Features:**
16+
- Decorator-based tool, resource, and prompt definitions
17+
- Automatic schema generation from type hints
18+
- Built-in HTTP server support with Starlette
19+
- Context injection support
20+
- Minimal boilerplate code
21+
22+
### 2. MCP Built-in FastMCP Server (`main.py`)
23+
24+
Uses `mcp.server.fastmcp.FastMCP` from the official MCP Python SDK - a simpler high-level API.
25+
26+
**Features:**
27+
- Decorator-based tool, resource, and prompt definitions
28+
- Automatic schema generation
29+
- Context injection support
30+
- STDIO transport only
31+
- Less boilerplate than low-level API
32+
33+
### 3. Low-Level Server (`main_lowlevel.py`)
34+
35+
Uses `mcp.server.lowlevel.Server` from the official MCP Python SDK - provides maximum control.
36+
37+
**Features:**
38+
- Manual schema definitions with full JSON Schema support
39+
- Explicit handler registration
40+
- Fine-grained control over protocol details
41+
- Direct access to MCP types
42+
- Best for complex custom behavior
43+
44+
## Common Features
45+
46+
All three examples demonstrate:
47+
48+
1. **Tools**: Functions that clients can call
49+
- `calculate_sum` - Add two numbers
50+
- `calculate_product` - Multiply two numbers
51+
- `greet_user` - Generate personalized greetings
52+
- `trigger_error` - Test Sentry error tracking
53+
54+
2. **Resources**: Data endpoints that clients can access
55+
- `config://settings` - Server configuration
56+
- `data://users` - User list
57+
- `data://stats` - Server statistics (low-level only)
58+
59+
3. **Prompts**: Reusable prompt templates
60+
- `code_review` - Code review template
61+
- `debug_assistant` - Debugging assistance template
62+
- `sql_query_helper` - SQL query help (low-level only)
63+
64+
## Running the Servers
65+
66+
### Prerequisites
67+
```bash
68+
# Install dependencies
69+
uv sync
70+
```
71+
72+
### FastMCP Library Server (HTTP)
73+
```bash
74+
# Using the script (automatically starts MCP inspector)
75+
./run_fastmcp.sh
76+
77+
# Or directly (just the server, no inspector)
78+
uv run python main_fastmcp.py
79+
```
80+
81+
This starts an HTTP server on `http://127.0.0.1:8000` that you can interact with via HTTP requests. The `run_fastmcp.sh` script automatically starts the MCP inspector tool for testing.
82+
83+
### MCP Built-in FastMCP Server (STDIO)
84+
```bash
85+
# Using the script (automatically starts MCP inspector)
86+
./run.sh
87+
88+
# Or directly (just the server, no inspector)
89+
uv run python main.py
90+
```
91+
92+
The `run.sh` script automatically starts the MCP inspector tool for testing.
93+
94+
### Low-Level Server (STDIO)
95+
```bash
96+
# Using the script (server only)
97+
./run_lowlevel.sh
98+
99+
# Or directly
100+
uv run python main_lowlevel.py
101+
```
102+
103+
**Note:** The `run_lowlevel.sh` script does NOT automatically start the MCP inspector. To test this server, you need to manually start the inspector:
104+
```bash
105+
npx @modelcontextprotocol/inspector
106+
```
107+
108+
## Using with MCP Clients
109+
110+
The STDIO-based servers (`main.py` and `main_lowlevel.py`) can be used with any MCP-compatible client like [Claude Desktop](https://claude.ai/download).
111+
112+
### Example Client Configuration
113+
114+
For Claude Desktop, add to your configuration file:
115+
116+
**MCP Built-in FastMCP Server:**
117+
```json
118+
{
119+
"mcpServers": {
120+
"example-fastmcp": {
121+
"command": "uv",
122+
"args": ["run", "python", "/path/to/test-mcp/main.py"],
123+
"env": {
124+
"SENTRY_DSN": "your-sentry-dsn-here"
125+
}
126+
}
127+
}
128+
}
129+
```
130+
131+
**Low-Level Server:**
132+
```json
133+
{
134+
"mcpServers": {
135+
"example-lowlevel": {
136+
"command": "uv",
137+
"args": ["run", "python", "/path/to/test-mcp/main_lowlevel.py"],
138+
"env": {
139+
"SENTRY_DSN": "your-sentry-dsn-here"
140+
}
141+
}
142+
}
143+
}
144+
```
145+
146+
**FastMCP Library Server:**
147+
148+
The FastMCP Library server runs as an HTTP server and requires a different client setup that supports HTTP-based MCP connections. Alternatively, you can use it programmatically via HTTP requests.
149+
150+
## Testing with MCP Inspector
151+
152+
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a developer tool for testing and debugging MCP servers. It provides an interactive web interface to test your server's tools, resources, and prompts.
153+
154+
### Automatic Inspector Startup
155+
156+
The following run scripts **automatically start the MCP inspector** for you:
157+
- `./run.sh` (MCP Built-in FastMCP server)
158+
- `./run_fastmcp.sh` (FastMCP Library server)
159+
160+
### Manual Inspector Startup
161+
162+
For the **low-level server** (`run_lowlevel.sh`), the inspector is NOT started automatically. You need to manually start it:
163+
164+
```bash
165+
# First, start the server
166+
./run_lowlevel.sh
167+
168+
# Then, in a separate terminal, start the inspector
169+
npx @modelcontextprotocol/inspector
170+
```
171+
172+
### Testing Each Server Implementation Manually
173+
174+
If you prefer to run the inspector manually for any server:
175+
176+
**MCP Built-in FastMCP Server (`main.py`):**
177+
```bash
178+
npx @modelcontextprotocol/inspector uv run python main.py
179+
```
180+
181+
**Low-Level Server (`main_lowlevel.py`):**
182+
```bash
183+
npx @modelcontextprotocol/inspector uv run python main_lowlevel.py
184+
```
185+
186+
**Note:** The FastMCP Library server (`main_fastmcp.py`) runs as an HTTP server and can be tested by navigating to `http://127.0.0.1:8000` in your browser after starting it.
187+
188+
### Using the Inspector
189+
190+
Once the inspector starts, it will:
191+
1. Open a web interface in your browser (typically at `http://localhost:5173`)
192+
2. Connect to your MCP server via STDIO
193+
3. Allow you to interactively test all tools, resources, and prompts
194+
4. Display request/response data for debugging
195+
196+
This is the recommended way to test and debug your MCP servers during development.
197+
198+
## Comparison: FastMCP Library vs MCP Built-in FastMCP vs Low-Level
199+
200+
| Feature | FastMCP Library | MCP Built-in FastMCP | Low-Level |
201+
|---------|-----------------|---------------------|-----------|
202+
| **Package** | `fastmcp` (standalone) | `mcp.server.fastmcp` | `mcp.server.lowlevel` |
203+
| **Code Style** | Decorator-based | Decorator-based | Handler registration |
204+
| **Boilerplate** | Minimal | Minimal | More verbose |
205+
| **Schema** | Auto-generated | Auto-generated | Manual JSON schema |
206+
| **Transport** | HTTP + STDIO | STDIO only | STDIO only |
207+
| **HTTP Support** | ✅ Built-in (Starlette) | ❌ | ❌ |
208+
| **Control** | Medium | Medium | Maximum |
209+
| **Best For** | Modern apps, HTTP APIs | Simple STDIO servers | Complex custom behavior |
210+
| **Learning Curve** | Easy | Easy | Steeper |
211+
212+
### When to Use FastMCP Library
213+
- Modern applications with HTTP support
214+
- Want to expose MCP server over the web
215+
- Need CORS, middleware, or HTTP-specific features
216+
- Prefer the most up-to-date FastMCP implementation
217+
218+
### When to Use MCP Built-in FastMCP
219+
- Simple STDIO-based servers
220+
- Want decorator-based API without external dependencies
221+
- Working with official MCP Python SDK
222+
- Traditional MCP server patterns
223+
224+
### When to Use Low-Level
225+
- Need fine-grained control over protocol
226+
- Custom protocol behavior or validation
227+
- Complex error handling requirements
228+
- Performance-critical applications
229+
230+
**See [COMPARISON.md](./COMPARISON.md) for detailed side-by-side code examples.**
231+
232+
## Sentry Integration
233+
234+
All three examples include Sentry integration using the `MCPIntegration()`. This provides:
235+
- Automatic error tracking for all MCP operations
236+
- Performance monitoring for tool calls
237+
- Breadcrumbs for debugging MCP interactions
238+
- Distributed tracing support
239+
240+
Configure Sentry by setting the `SENTRY_DSN` environment variable.
241+
242+
## Additional Resources
243+
244+
### MCP Documentation & Tools
245+
- [Model Context Protocol Official Site](https://modelcontextprotocol.io/)
246+
- [MCP GitHub Organization](https://github.com/modelcontextprotocol)
247+
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
248+
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - Test and debug MCP servers
249+
- [FastMCP Library](https://github.com/jlowin/fastmcp) - Standalone FastMCP with HTTP support
250+
- [MCP Specification](https://spec.modelcontextprotocol.io/)
251+
252+
### Client Applications
253+
- [Claude Desktop](https://claude.ai/download) - Official MCP client from Anthropic
254+
- [MCP Clients List](https://github.com/modelcontextprotocol/servers#clients) - Other MCP-compatible clients
255+

0 commit comments

Comments
 (0)