Skip to content

Quickstart

From nothing to a tested server running in your MCP host.

1. Create a project

pipx install ouncemcp        # or: uv tool install ouncemcp
ouncemcp init notes-server
cd notes-server
uv venv && uv pip install -e ".[dev]"

The current release is the 1.0 release candidate; while no stable release exists, pip, pipx and uv install it without extra flags. To work from a checkout instead, run uv pip install -e /path/to/ouncemcp -e ".[dev]".

init writes:

File What it is
server.py notes.search (read) and notes.add (write)
tests/test_server.py Calls both tools, checks errors and the token budget
.github/workflows/ci.yml Runs the tests and ouncemcp check
pyproject.toml, README.md, .gitignore Project files

2. Test and check

uv run pytest                    # 6 tests pass as generated
uv run ouncemcp check server.py  # token budget per tool, discovery mode, lints

3. Develop with hot reload

uv run ouncemcp dev server.py

dev prints the budget summary, serves on http://127.0.0.1:8000/mcp, restarts when you save a file, and prints one line per tool call with the tokens the result used:

[ouncemcp] notes-server: 2 tools
  notes.search     182 tokens
  notes.add        118 tokens
  startup context: 300 tokens (warn at 4,000); discovery: direct (direct costs 300 tokens, within the 4,000-token threshold); counted with o200k_base
[ouncemcp] call notes.search ok 41/2,000 tokens 0.6 ms

4. Connect a host

Over stdio, hosts start the server themselves. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "notes": {"command": "uv", "args": ["run", "--directory", "/path/to/notes-server", "python", "server.py"]}
  }
}

For VS Code, add to .vscode/mcp.json:

{
  "servers": {
    "notes": {"type": "stdio", "command": "uv", "args": ["run", "python", "server.py"]}
  }
}

5. Write your own tools

Every tool declares an effect and uses Pydantic models for input and output:

@server.tool(name="tickets.close", effect=Effect.WRITE, policy=require_scopes("tickets:write"))
async def close(args: CloseInput, ctx: ToolContext) -> Closed:
    """Close a ticket. Side effect: notifies the requester."""
    ...

Next: budgets, securing tools.