Build a read-only MCP tool server for agent queries

Goal

Provide discoverable, constrained MCP queries with no write side effects.

Steps

1. Choose one read-only business query and grant minimum read privileges at the data layer. [mcp-tools] [mcp-errors]
2. Register with @mcp.tool() and type hints; constrain pagination with Annotated[int, Field(ge=1, le=50)]. [mcp-tools] [mcp-errors]
3. If you set read_only_hint=True, treat it only as a client hint; enforce read-only access in database/service permissions. [mcp-tools] [mcp-errors]
4. Convert exceptions to controlled MCP errors; never return stack traces, connection strings, or secrets. [mcp-tools] [mcp-errors]
5. Test valid, unauthorized, invalid, and oversized-page requests; verify the data layer rejects writes. [mcp-tools] [mcp-errors]

How to verify

Tests should prove the tool reads only authorized scope and errors reveal no internal details.

Troubleshooting

If a test can mutate data, enforce read-only permissions in the data layer rather than relying on the tool description.