Build your own MCP server: a minimal read-only Python tool

Build your own MCP server in Python by registering a narrow function with the official SDK, running it over stdio, and testing it with MCP Inspector before connecting an editor client. Start with a read-only lookup over fictional data: it lets you learn discovery, arguments and results without credentials or access to business systems. The official Python SDK provides the server machinery used below.

What it can do

Our example answers a specific support question: which instruction belongs to a delivery or returns topic? The data is deliberately fictional. A caller chooses a topic and receives the corresponding text; the function cannot change orders, open files or contact a website because its implementation contains none of those operations.

The name lookup_policy below belongs to this tutorial, not to an existing integration. Use it as a small contract: known topics produce known answers; unsupported topics must fail validation. This makes a more useful first exercise than handing an assistant an unrestricted filesystem reader.

MCP tools have names and input schemas. Clients discover them with tools/list and invoke them with tools/call; the SDK handles that exchange. The tools specification, reviewed on 30 Oct 2026, also recommends a human being able to deny calls. For background, read what MCP is and the MCP versus APIs comparison.

How to connect it safely

1. Prepare an isolated project. Open an empty folder in VS Code or your usual editor. As of 30 Oct 2026, the SDK installation documentation describes the stable v2 line and requires Python 3.11 or later. The example follows that API; check the current documentation before mixing it with an older tutorial. With Python available, run:

sh python -m venv .venv

Install the development dependency using that environment's interpreter. On macOS/Linux:

sh .venv/bin/python -m pip install 'mcp[cli]'

On Windows PowerShell:

powershell .venv\Scripts\python.exe -m pip install 'mcp[cli]'

Record the resolved dependency versions in your project's dependency lock before sharing it. Keep this exercise separate from a repository containing credentials or customer records.

2. Create server.py. Save the complete example below. Literal restricts accepted topic values. The SDK tools guide documents decorators, schemas derived from type hints, and the annotation syntax used here.

```python from typing import Literal

from mcp.server import MCPServer from mcp.types import ToolAnnotations

mcp = MCPServer("Demo policy lookup")

POLICIES = { "delivery": "Demo only: ask support about delivery changes.", "returns": "Demo only: contact support before returning an item.", }

@mcp.tool( annotations=ToolAnnotations( read_only_hint=True, open_world_hint=False, ) ) def lookup_policy(topic: Literal["delivery", "returns"]) -> str: """Return fictional guidance for an allowed support topic.""" return POLICIES[topic]

if name == "main": mcp.run(transport="stdio") ```

The annotations describe intended behaviour. They do not prevent writes or restrict operating-system permissions. The read-only property here comes from the function body. Keep the fictional labels when demonstrating it so nobody mistakes its answers for your company's approved policy.

3. Check startup, then use Inspector. Run the file with the same environment's Python. A stdio server normally waits for protocol input without a greeting; that behaviour is explained in Running your server. Stop the manual process before starting your test client.

With Node available, use the browser-based MCP Inspector. Its documentation, checked on 30 Oct 2026, requires Node 22.19.0 or newer. From the project folder on macOS/Linux:

sh npx @modelcontextprotocol/inspector .venv/bin/python server.py

On Windows PowerShell:

powershell npx @modelcontextprotocol/inspector .venv\Scripts\python.exe server.py

npx can download the Inspector package; review the package prompt before proceeding. Open the local URL it prints and keep its access token private. Connect using stdio and inspect the Tools view.

4. Test the boundary directly. Confirm lookup_policy appears with a required topic parameter. Call it with {"topic":"returns"} and then {"topic":"delivery"}; compare each result with the literal text in POLICIES. Try an unsupported value such as {"topic":"billing"} and an empty argument object. Both should be rejected rather than producing invented guidance. If the form prevents invalid input, submit the same call through Inspector's CLI. These checks establish the example's behaviour before an assistant paraphrases anything.

5. Register a client launch command. For the VS Code MCP client, create or carefully merge .vscode/mcp.json using the servers wrapper documented in the official host connection guide:

json { "servers": { "demo-policy": { "type": "stdio", "command": "/absolute/path/to/project/.venv/bin/python", "args": ["/absolute/path/to/project/server.py"] } } }

Replace both paths with real absolute paths. On Windows, use the environment's python.exe and escape backslashes in JSON, or use forward slashes. Review the server trust prompt and use MCP: List Servers to inspect its state. Your editor also needs an enabled MCP-capable chat client; check its current account requirements. See the VS Code MCP guide for the wider setup.

6. Observe a chat call. Ask the client to use lookup_policy for returns. Inspect the actual arguments and result, then compare the answer with the demo text. Keep approval prompts enabled while learning. A successful chat answer alone is weaker evidence than seeing the tool invocation and its returned content.

When this does not work

An import error usually means the launch command selected a different Python environment, or the installed SDK does not match this example. Re-run the exact configured command in a terminal and compare it with the current SDK documentation. A missing server can also result from a stale client configuration or a relative path resolving somewhere unexpected; the host connection guide covers these failures.

Keep application diagnostics on stderr through Python logging. The official server tutorial warns that stdout is the stdio protocol channel: startup messages or wrapper scripts can corrupt it.

Read-only does not mean confidential. Only put approved demo text in this example: a client can include returned text in its conversation. Adding database access, files or remote APIs changes the design. Before extending it, define authorization, output filtering and operational limits using the server security checklist. A team service also needs a deployment and access-control design; changing the transport to HTTP does not supply those decisions.

Where Tvijo fits

As of 30 Oct 2026, the DSHREM VS Code extension is an editor entry point for asking about selected code. Use it beside server.py to discuss the function or a failing test, then run Inspector yourself in the terminal. TvijoCode embeds the extension in a test editor build; its published description identifies unsigned Windows builds without automatic updates. Choose an editor that meets your installation policy.

Tvijo MCP's release status gives a real example of the separate server role. As of 30 Oct 2026, its release report dated 28 Oct records published consultation in package 0.1.1; the merged and tagged 0.2.0 diff-review release awaits npm publication. Editor provider integration and safe delegation remain planned phases. Do not assume installing the extension connects this tutorial server or turns Tvijo into a client for every MCP server.

As of 30 Oct 2026, Tvijo's offers show Try at $0, with up to 5 tasks, 50,000 tokens or $0.05 of sponsored usage, whichever comes first, from a shared $1 daily pool funded by TVIJO. Service credit is shown at $10 as a prepaid-credit request, with metered provider usage plus an 8% service markup. Payment collection is not activated; an order is not a charge.

FAQ

Do I need an API key for this example?

The example server and its direct Inspector calls need no business API credentials. An assistant client has its own account and usage requirements; check those separately.

Can this server read my project files?

This implementation only looks up text in its embedded dictionary. MCP annotations do not sandbox the process: inspect any replacement code and its operating-system access before running it.

How do I turn the demo into a useful business tool?

Replace the fictional dictionary with approved information only after defining who may retrieve it and what may leave the system. Keep the input narrow and repeat the boundary tests. Continue with AI agents explained.