# usefastmcp

A simple [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server built with [FastMCP](https://gofastmcp.com/).

This project demonstrates how to expose custom tools as MCP servers over two different transports — **stdio** (local, default) and **HTTP** (remote).

---

## Project Structure

```
usefastmcp/
├── pyproject.toml            # Project config & dependencies (fastmcp)
├── uv.lock                   # Locked dependency versions
├── .python-version           # Python 3.13
├── servers/
│   ├── stdioserver.py        # MCP server over stdio transport
│   └── httpserver.py         # MCP server over HTTP transport
└── .vscode/
    └── mcp.json              # VS Code Copilot MCP configuration
```

---

## Requirements

- **Python 3.13+**
- **[uv](https://docs.astral.sh/uv/)** package manager

---

## Setup

```bash
uv sync
```

This creates the virtual environment and installs all dependencies (including `fastmcp`).

---

## Available Tools

Both servers expose the same tools:

| Tool | Signature | Description |
|------|-----------|-------------|
| `roll_dice` | `roll_dice()` | Returns a random integer between 1 and 6 |
| `add_numbers` | `add_numbers(first: int, second: int)` | Adds two integers and returns the sum |

---

## Running the Server

### 1. Stdio Transport (default)

Runs over standard input/output — ideal for local host applications that launch the process directly.

```bash
uv run servers/stdioserver.py
```

### 2. HTTP Transport

Runs as an HTTP server on `http://127.0.0.1:8000` — useful for remote clients and web-based access.

```bash
uv run servers/httpserver.py
```

> **Note:** The FastMCP CLI (`fastmcp run <file>`) always forces stdio transport and ignores the `transport="http"` option in your code. Run `uv run servers/httpserver.py` directly to use HTTP transport.

---

## VS Code Integration

This project includes `.vscode/mcp.json` for use with VS Code Copilot. The config launches the stdio server automatically.

1. Open the project in VS Code
2. Restart VS Code (or reload the window) so the MCP server is picked up
3. The `roll_dice` and `add_numbers` tools become available to the Copilot agent

![VS Code MCP Integration](image.png)