Connector Starter

Changelog

• 1.0.0, 22 October 2026: first release

Connector Starter

Version 1.0.0

A small, working Model Context Protocol (MCP) server in two languages: TypeScript and Python. Each starter has one useful example tool, tests that run without a network, and a README. Copy the folder for your language, rename it and start adding your own tools.

MCP is an open protocol that lets an assistant or agent call tools, read resources and use prompts that live outside the app it runs in. You write a server once, and any client that speaks MCP can connect to it.

Who it's for

• Developers who want to expose an API, a database query or an internal script to their assistant or coding agent
• Teams that need a clean, tested starting point instead of copying snippets from several places
• Anyone who prefers to read a small, complete example before reading a specification

You should be comfortable with a terminal and with either Node.js or Python.

How to use it in 5 minutes

1. Pick a language. Copy typescript/ or python/ to where your project lives.
2. Install and test it. TypeScript: npm install, npm run build, npm test. Python: create a virtual environment, pip install -e ".[dev]", pytest.
3. Open the server in the MCP Inspector (see "Testing with the MCP Inspector" below) and call text_stats by hand.
4. Add the server to your MCP client using the config in "Connecting to a client".
5. Read "Adding a second tool" and "Security notes for tools" before you write your own.

File map

The example tool

Both starters register the same tool, so a client sees identical behaviour whichever language you run.

text_stats counts the words, characters and lines in a piece of text and estimates the reading time.

Example result for "Hello world\nSecond line here":

{ "words": 5, "characters": 28, "lines": 2, "reading_time_seconds": 2 }

It is deliberately simple: deterministic, no network, no secrets. That makes it a good template for testing and a safe thing to leave in while you build.

Running the starters

TypeScript (Node.js 20 or newer):

cd typescript
npm install
npm run build
npm start

Python (3.10 or newer), macOS and Linux:

cd python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
connector-starter

On Windows, activate with .\.venv\Scripts\Activate.ps1 instead.

Both servers speak MCP over stdio. Started by hand, they wait silently for input. That is normal: a client normally starts the process for you.

Connecting to a client

Most desktop and editor clients read a JSON config with an mcpServers object. The file name and location differ by client, so check its documentation for where the file lives. The shape is the same. Always use absolute paths, because the client may start the server from a different working directory.

TypeScript (after npm run build):

{
  "mcpServers": {
    "connector-starter": {
      "command": "node",
      "args": ["/absolute/path/to/connector-starter/typescript/dist/index.js"]
    }
  }
}

Python, macOS and Linux (point at the virtual environment so the right packages load):

{
  "mcpServers": {
    "connector-starter": {
      "command": "/absolute/path/to/connector-starter/python/.venv/bin/connector-starter",
      "args": []
    }
  }
}

Python on Windows (backslashes must be doubled in JSON):

{
  "mcpServers": {
    "connector-starter": {
      "command": "C:\\projects\\connector-starter\\python\\.venv\\Scripts\\python.exe",
      "args": ["-m", "connector_starter"]
    }
  }
}

If your server needs settings such as an API key, most clients accept an env object next to args. Keep real values in that local config or in your secret store, never in the repository.

After editing the config, restart the client or reload its MCP servers. If the tool does not appear, check the client's MCP log first. The usual causes are a relative path, a missing build, or a virtual environment that was never installed into.

Adding a second tool

Each language README shows a complete second tool (slugify). The pattern is the same in both:

1. Write the logic as a plain function you can unit test.
2. Register it inside createServer() or create_server() with a clear name, a one-sentence description and a strict input schema.
3. Add annotations: readOnlyHint for tools that change nothing, destructiveHint for tools that delete or overwrite, openWorldHint for tools that reach the internet.
4. Add tests: one for the plain function, one call through the in-memory client and one invalid-input case.
5. Rebuild (TypeScript) and reload the server in your client.

Naming tips: use short snake_case verbs or nouns (search_orders, get_invoice). Write the description for the model that will read it: say what the tool does, what it returns and when not to use it. Keep the number of tools small; many similar tools make selection worse.

Testing with the MCP Inspector

The MCP Inspector is the official tool for poking at a server by hand. It runs with npx, so nothing needs to be installed globally.

Open the browser interface:

cd typescript
npx @modelcontextprotocol/inspector node dist/index.js

cd python
npx @modelcontextprotocol/inspector .venv/bin/connector-starter

On Windows, use .venv\Scripts\connector-starter.exe for the Python command. The Inspector prints a local URL. Open it, press Connect, go to Tools, list the tools and run text_stats with your own text. Try a words_per_minute of 5 to see how a validation error is reported.

For scripts and CI, the Inspector also has a command-line mode:

npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/call --tool-name text_stats --tool-arg "text=one two three"

The automated tests in each starter cover the same ground without starting a process, so run npm test or pytest on every change and use the Inspector for exploration.

Security notes for tools

A tool is code that an agent can run on your behalf, often with your permissions. Treat every argument as untrusted input, even when you trust the person using the client: the arguments are chosen by a model, and the model can be steered by content it reads.

• Validate input. Give every argument a type, a length or range limit and, where it fits, an enum or pattern. The schema is enforced before your code runs; add checks in code for anything a schema cannot express, such as "this path must stay inside this folder".
• Least privilege. Give the server only the access it needs: a read-only database user, a scoped API token, one directory instead of the whole disk. Split read and write actions into separate tools, and mark write tools with destructiveHint so clients can ask for confirmation.
• Never return secrets. Do not echo tokens, keys, connection strings or full environment variables in results or error messages. Return only the fields the caller needs. Remember that results are shown to the model and may be logged by the client.
• Set timeouts. Put a timeout on every network call, subprocess and query, and cap the size of what you return. A tool that hangs blocks the whole conversation.
• No shell strings. If a tool must run a program, pass arguments as a list and never build a shell command from input. Never pass input to eval or similar.
• Watch paths and URLs. Resolve file paths and reject anything outside an allowed root. For URLs, allow-list hosts and block internal addresses so the tool cannot be used to reach your private network.
• Keep stdout clean. On stdio, stdout is the protocol channel. Log to stderr or to a file.
• Pin and review dependencies. Commit your lockfile in your own project, keep the SDK up to date and read the release notes before major upgrades.

Package versions

This release was built and tested against:

No lockfile is included, so npm install and pip install resolve the newest matching versions. Commit the lockfile your install creates so your builds stay repeatable.

A note on limits

These are starters, not frameworks. They use stdio only; remote hosting over Streamable HTTP, authentication, rate limiting and deployment are out of scope. The security notes reduce risk but cannot make a tool safe on their own; review any tool that writes data or touches the network before you connect it to an agent. MCP and its SDKs change quickly, so check the release notes when you upgrade.

Licence

MIT License. See LICENSE.txt.

Connector Starter (Python)

A minimal Model Context Protocol server written in Python with the official mcp package. It exposes one tool, text_stats, over stdio.

Requirements

• Python 3.10 or newer
• The mcp package, version 2.3 or newer within the 2.x line (installed for you below)

Set up

macOS and Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Run

connector-starter

python -m connector_starter does the same thing. The server reads JSON-RPC messages on stdin and writes replies on stdout, so it will sit quietly in the terminal. That is expected. Stop it with Ctrl+C. To talk to it, connect an MCP client or the MCP Inspector, as described in the kit README.

Test

pytest

The tests connect an in-process mcp.Client to create_server(), so no subprocess or network is involved. They list the tools, call text_stats with valid input and check that invalid input comes back as a tool error.

Files

The example tool

text_stats takes:

It returns words, characters, lines and reading_time_seconds as structured content. The return type is a Pydantic model, so MCPServer publishes an output schema for it automatically.

Counting rules:

• Words are runs of non-whitespace characters.
• Characters are Unicode code points, so an accented letter or an emoji counts as one.
• Lines are split on \n, \r\n or \r. A trailing line break does not add an empty line.
• Reading time is rounded up to the next whole second.

Adding a tool

Add another decorated function inside create_server():

@server.tool(
    name="slugify",
    description="Turn a title into a lowercase, hyphenated URL slug.",
    annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=False),
)
def slugify(
    title: Annotated[str, Field(min_length=1, max_length=200, description="The title to convert.")],
) -> str:
    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
    return slug or "untitled"

Type hints and Field constraints become the tool's JSON Schema, and MCPServer validates arguments before your function runs. Keep the logic in a plain function when it is more than a few lines, so it can be unit tested without a client. Then add a test in tests/test_server.py that calls the new tool through Client(create_server()).

Note on package versions

Version 2 of the mcp package renamed the high-level server class to MCPServer (in mcp.server.mcpserver) and added mcp.Client, which can connect straight to a server object for tests. If you need to stay on 1.x, the equivalent class is FastMCP in mcp.server.fastmcp, and the tests would use create_connected_server_and_client_session from mcp.shared.memory instead.

Connector Starter (TypeScript)

A minimal Model Context Protocol server written in TypeScript with the official @modelcontextprotocol/sdk package. It exposes one tool, text_stats, over stdio.

Requirements

• Node.js 20 or newer
• npm (comes with Node.js)

Set up and build

npm install
npm run build

npm run build compiles src/ into dist/.

Run

npm start

This runs node dist/index.js. During development, npm run dev runs the TypeScript source directly with tsx, with no build step.

The server reads JSON-RPC messages on stdin and writes replies on stdout, so it will sit quietly in the terminal. That is expected. Stop it with Ctrl+C. To talk to it, connect an MCP client or the MCP Inspector, as described in the kit README.

Never write to stdout from a stdio server (for example with console.log). Stdout carries the protocol, and stray output corrupts it. Use console.error for logs; it goes to stderr.

Test

npm test

The tests use the Node.js built-in test runner. They connect the SDK Client to createServer() through InMemoryTransport.createLinkedPair(), so no subprocess or network is involved. They list the tools, call text_stats with valid input and check that invalid input comes back as a tool error.

Scripts

Files

Keeping createServer() separate from the transport is deliberate. Tests and other transports (such as Streamable HTTP) can reuse the same server without touching stdio.

The example tool

text_stats takes:

It returns words, characters, lines and reading_time_seconds, both as structured content (matching the declared output schema) and as a JSON text block for clients that only read text.

Counting rules:

• Words are runs of non-whitespace characters.
• Characters are Unicode code points, so an accented letter or an emoji counts as one.
• Lines are split on \n, \r\n or \r. A trailing line break does not add an empty line.
• Reading time is rounded up to the next whole second.

The tool is marked read-only, idempotent and closed-world through annotations. Clients may use these hints when deciding whether to ask the user before a call.

Adding a tool

Register another tool inside createServer(), before return server:

server.registerTool(
  "slugify",
  {
    title: "Slugify",
    description: "Turn a title into a lowercase, hyphenated URL slug.",
    inputSchema: {
      title: z.string().min(1).max(200).describe("The title to convert."),
    },
    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
  },
  async ({ title }) => {
    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
    return { content: [{ type: "text", text: slug || "untitled" }] };
  },
);

The zod shape becomes the tool's JSON Schema, and the SDK validates arguments before your handler runs. Keep the logic in a plain exported function when it is more than a few lines, so it can be unit tested without a client. Then add a test in test/server.test.ts that calls the new tool through the in-memory client.

Publishing as a command

package.json declares a connector-starter bin that points at dist/index.js, and the entry file starts with a Node shebang. After npm run build, npm link makes connector-starter available on your PATH. If you publish the package, remove "private": true and pick a unique package name first.