Skip to main content
Glama
mcp-server-starter

mcp-server-starter

by humzagk

mcp-server-starter

tests

A production-minded template for putting your own product behind an MCP server, so AI assistants such as Claude can search and read your data (and, if you allow it, write to it).

You implement one small interface, ProductAdapter, for your product. The template handles the MCP side:

  • tools, resources and a prompt

  • input validation and structured output

  • error handling that never leaks secrets

  • stdio and Streamable HTTP transports

  • read-only by default

  • tests

 AI assistant  ──MCP──▶  createServer()  ──▶  ProductAdapter  ──▶  your product
 (Claude, ...)           tools/resources       search / get        (DB, REST API,
                         prompts, errors       list / create        SaaS, files)

It ships with three adapters:

Adapter

Use it for

memory

Trying it out, tests, and as the smallest reference implementation

rest

Any JSON REST API, configured with environment variables

github

A real-world example that exposes one GitHub repo's issues and PRs

Quick start

Requires Node.js 22+.

git clone https://github.com/humzagk/mcp-server-starter.git
cd mcp-server-starter
npm install
npm run build
npm test

Try it in the MCP Inspector:

npm run inspect

Connect it to Claude Code

claude mcp add help-centre -- node /absolute/path/to/mcp-server-starter/dist/index.js

Connect it to Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "help-centre": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-starter/dist/index.js"],
      "env": { "MCP_ADAPTER": "memory" }
    }
  }
}

Then ask something like "How do I reset my password?". The assistant calls search_items and then get_item.

Related MCP server: @shieldlabs-ai/mcp

What the server exposes

Kind

Name

Description

Tool

search_items

Search with query and limit. Returns ranked matches with snippets, as text and as structured content. Marked read-only.

Tool

get_item

Read one item in full by id. Unknown ids return a tool error the model can recover from. Marked read-only.

Tool

create_item

Create an item. Only registered when MCP_ALLOW_WRITES=true and the adapter implements create.

Resource

item://{id}

Each item as Markdown. Listable when the adapter implements list.

Prompt

summarize_item

Embeds an item and asks for a three-bullet summary plus action items.

Adapting it to your product

1. Implement the adapter

search and get are all you need for a read-only server:

// src/adapters/acme.ts
import { AdapterError, type Item, type ProductAdapter } from "../adapter.js";

export class AcmeTicketsAdapter implements ProductAdapter {
  readonly name = "Acme Helpdesk";
  readonly itemDescription = "support tickets";

  constructor(private apiKey: string) {}

  async search(query: string, limit: number): Promise<Item[]> {
    const res = await fetch(`https://api.acme.example/tickets?q=${encodeURIComponent(query)}&limit=${limit}`, {
      headers: { Authorization: `Bearer ${this.apiKey}` },
    });
    if (!res.ok) throw new AdapterError(`Acme API returned HTTP ${res.status}`); // shown to the model
    const tickets = await res.json();
    return tickets.map((t: any) => ({
      id: String(t.id),
      title: t.subject,
      content: t.description,
      metadata: { status: t.status, priority: t.priority },
      updatedAt: t.updated_at,
    }));
  }

  async get(id: string): Promise<Item | null> {
    /* fetch one ticket; return null if it does not exist */
    return null;
  }
}

Optional methods:

  • list(limit, cursor) lets clients browse items as resources.

  • create(input) adds the create_item tool, but only when writes are enabled.

2. Register it

Add a case to buildAdapter() in src/index.ts:

case "acme":
  return new AcmeTicketsAdapter(env.ACME_API_KEY ?? "");

Or use the library directly in your own entry point:

import { createServer } from "mcp-server-starter";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

await createServer(new AcmeTicketsAdapter(process.env.ACME_API_KEY!)).connect(new StdioServerTransport());

3. Test it

test/server.test.ts shows how to drive the server through a real MCP client over an in-memory transport. Copy one of those tests and point it at your adapter.

No code: the REST adapter

If your product already has a JSON API shaped like GET /items?q=, GET /items/{id} and POST /items, configure it instead of writing code:

MCP_ADAPTER=rest \
MCP_REST_BASE_URL=https://api.example.com/v1 \
MCP_REST_API_KEY=... \
MCP_PRODUCT_NAME="Example CRM" \
MCP_ITEM_DESCRIPTION="customer records" \
node dist/index.js

You can change the paths with MCP_REST_SEARCH_PATH, MCP_REST_ITEM_PATH and MCP_REST_CREATE_PATH. Records are mapped by defaultToItem, which recognises common field names (id/uuid, title/name/subject, content/body/description). Pass your own toItem for anything else.

Real-world example: GitHub issues

MCP_ADAPTER=github GITHUB_REPO=modelcontextprotocol/typescript-sdk node dist/index.js

See src/adapters/github.ts for how it scopes searches, maps issues onto items and handles rate limits. Set GITHUB_TOKEN for higher rate limits or private repos.

Running over HTTP

MCP_HTTP_TOKEN=change-me node dist/index.js --http --port 3000
# MCP endpoint: http://127.0.0.1:3000/mcp   health check: GET /health
  • Stateless Streamable HTTP: each request gets a fresh server, so you can run several instances behind a load balancer with no session store.

  • Binds to 127.0.0.1 by default. Pass --host 0.0.0.0 to expose it on the network, and set a token when you do.

  • Bearer token (MCP_HTTP_TOKEN), compared in constant time.

  • DNS-rebinding protection: only localhost and 127.0.0.1 are accepted as Host by default. Set MCP_ALLOWED_HOSTS=mcp.example.com behind a real hostname.

  • Request body limit (1 MB) and JSON-RPC error responses.

Connect Claude Code to it:

claude mcp add --transport http help-centre http://127.0.0.1:3000/mcp --header "Authorization: Bearer change-me"

For multi-user deployments, put the server behind your existing auth (OAuth or an API gateway) and pass the user's identity into your adapter. A shared bearer token is a starting point, not per-user access control.

Security notes

  • Read-only unless you opt in. Write tools only exist when MCP_ALLOW_WRITES=true. Tools carry readOnlyHint and destructiveHint annotations so clients can ask the user before calling them.

  • Errors are safe by default. Only AdapterError messages reach the model. Anything else becomes "internal error" and is logged to stderr, so stack traces, connection strings and API keys stay on the server.

  • Inputs are validated with zod schemas (lengths, ranges) before your adapter sees them.

  • stdout is reserved for the protocol in stdio mode. Log with console.error.

  • Treat everything your product returns as untrusted text. It goes into a model's context, so don't expose data the connected user shouldn't see.

Project structure

src/
  adapter.ts          the ProductAdapter interface, Item type and AdapterError
  server.ts           createServer(): tools, resources, prompt, error handling
  http.ts             Streamable HTTP transport (auth, host checks, limits)
  index.ts            CLI entry point: picks the adapter and transport from env/flags
  lib.ts              library exports
  adapters/
    memory.ts         in-memory sample data
    rest.ts           configurable JSON REST adapter
    github.ts         GitHub issues and pull requests
test/                 vitest suites (in-memory MCP client, mock APIs, real HTTP server)

Scripts

Command

What it does

npm run build

Compile TypeScript to dist/

npm test

Run the test suite

npm run dev

Run from source with tsx

npm run inspect

Build and open the MCP Inspector

npm run typecheck

Type-check without emitting

License

MIT

Available Tools

2 tools
get_itemGet itemA
Read-only

Read one of the help-centre articles in full, by id.

Inputs: id (required). Returns: id, uri, title, content, +2 more

search_itemsSearch Example Help CentreA
Read-only

Search help-centre articles in Example Help Centre. Returns the best matches with a short snippet; call get_item for the full text.

Inputs: query (required), limit. Returns: items

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct roles: search_items finds articles with snippets, while get_item retrieves one article in full by id. The descriptions explicitly guide the agent to search first and fetch full text second, leaving no meaningful overlap.

    Naming Consistency5/5

    Both names use consistent snake_case verb_noun structure: search_items and get_item. The singular/plural difference is natural and predictable for retrieving one item versus searching many.

    Tool Count4/5

    Two tools are minimal but well matched to a simple read-only help-centre server: search and retrieve. The surface is slightly thinner than the typical 3–15 range, but neither tool feels redundant or out of place.

    Completeness5/5

    For a read-only help-centre article domain, search plus full retrieval covers the core workflow completely. There are no obvious missing create/update/delete operations, and search can serve as the discovery path when the article id is unknown.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes code-review and issue-triage tools to AI assistants over stdio, letting them evaluate unified pull-request diffs for maintainer remarks, slice diffs into categorized AST hunks, and classify GitHub issues by priority while synthesizing minimal reproduction stubs.
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read identification verdicts, search history, summarize entities, explain risk scores, and verify webhook signatures through read-only tools over stdio or streamable HTTP.
      6
      23 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables developers to expose product operations as model-callable tools over stdio or Streamable HTTP with bearer-token auth, per-client rate limits, host allow-listing, structured call logging, and a swappable backend for secure, testable deployments.
      3
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Gives AI agents access to a persistent document workspace, letting them search, read, and update notes, guides, and project documentation across a full catalog of tools, prompts, and resources. It connects either to the hosted Cloud endpoint over Streamable HTTP with OAuth or API-key auth, or to a self-hosted instance through a stdio bridge.
      MIT