mcp-server-starter
Exposes a GitHub repository's issues and pull requests through search and retrieval, with searches scoped to the configured repo and rate-limit handling; supports optional GITHUB_TOKEN for higher rate limits or private repos.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-starter How do I reset my password?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-starter
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 |
| Trying it out, tests, and as the smallest reference implementation |
| Any JSON REST API, configured with environment variables |
| 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 testTry it in the MCP Inspector:
npm run inspectConnect it to Claude Code
claude mcp add help-centre -- node /absolute/path/to/mcp-server-starter/dist/index.jsConnect 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 with |
Tool |
| Read one item in full by |
Tool |
| Create an item. Only registered when |
Resource |
| Each item as Markdown. Listable when the adapter implements |
Prompt |
| 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 thecreate_itemtool, 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.jsYou 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.jsSee 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 /healthStateless 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.0to 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
localhostand127.0.0.1are accepted asHostby default. SetMCP_ALLOWED_HOSTS=mcp.example.combehind 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 carryreadOnlyHintanddestructiveHintannotations so clients can ask the user before calling them.Errors are safe by default. Only
AdapterErrormessages 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 |
| Compile TypeScript to |
| Run the test suite |
| Run from source with |
| Build and open the MCP Inspector |
| Type-check without emitting |
License
Available Tools
2 toolsget_itemGet itemARead-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 CentreARead-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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Connect assistants to your workspace knowledge, skills, and work tools.
Gives AI agents direct access to your Sanity projects and guidance for working with them
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceExposes 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.1Apache 2.0

@shieldlabs-ai/mcpofficial
AlicenseAqualityBmaintenanceEnables 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.623 npmMIT- AlicenseAqualityCmaintenanceEnables 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.3MIT
- AlicenseNot gradedqualityAmaintenanceGives 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