# Example Mcp Server

> Reference MCP server built with the mctx framework — fork it as a starting template for your own MCP server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mctx-ai-example-mcp-server`
- **Verified:** Pending review
- **Seller:** [mctx-ai](https://agentstack.voostack.com/s/mctx-ai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mctx-ai](https://github.com/mctx-ai)
- **Source:** https://github.com/mctx-ai/example-mcp-server
- **Website:** https://mctx.ai

## Install

```sh
agentstack add mcp-mctx-ai-example-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Example MCP Server

> mctx — The best way to Build an MCP Server

The comprehensive reference implementation for [`@mctx-ai/mcp`](https://github.com/mctx-ai/mcp). Every framework capability in one well-commented file — clone it, study it, fork it as a template for your own MCP server.

---

## What This Example Demonstrates

`src/index.ts` covers every pattern the framework supports:

**Tool Patterns**
- **Sync string return** — `greet`: receives args, returns a formatted string; demonstrates environment variable configuration via `GREETING`
- **Object return** — `calculate`: returns a structured result object (auto-serialized to JSON); demonstrates input validation and error throwing
- **Progress notifications** — `analyze`: emits progress via `res.progress(current, total)`; demonstrates streaming updates during long-running operations
- **LLM sampling** — `smart-answer`: delegates to the client's LLM via `res.ask`; demonstrates graceful fallback when sampling is unavailable
- **User identity via context** — `whoami`: reads `mctx.userId`, the stable mctx user ID injected server-side by the platform; demonstrates graceful degradation outside mctx

**Resource Patterns**
- **Static URI** — `docs://readme`: exact URI, no parameters, returns plain text
- **Dynamic URI template** — `user://{userId}`: extracts `userId` from the URI path, returns a JSON profile

**Prompt Patterns**
- **Single-message** — `code-review`: returns a plain string that becomes one user message
- **Multi-message conversation** — `debug`: uses `conversation()` to build structured user/assistant dialogue

**Infrastructure**
- **Tool annotation hints** — every tool sets `readOnlyHint`, `destructiveHint`, `openWorldHint`, and `idempotentHint` with inline rationale explaining each choice
- **Structured logging** — `log.info`, `log.debug`, `log.warning`, `log.error`, and `log.notice` throughout
- **Environment variable configuration** — reads `process.env.GREETING` lazily inside the handler (not at module scope)
- **Comprehensive test coverage** — `src/index.test.ts` tests every tool, resource, and prompt via JSON-RPC 2.0 requests

---

## Usage in Conversation

Once connected to an MCP client, try phrases like these:

**Greetings and identity**
- "Greet Alice" — calls `greet` with `name: "Alice"`
- "Who am I?" — calls `whoami` to return your stable mctx user ID
- "Greet the whole team" — calls `greet` in a loop for each name

**Math and analysis**
- "What is 6 times 7?" — calls `calculate` with `operation: "multiply"`
- "Divide 10 by 0" — triggers the division-by-zero error path
- "Analyze quantum computing" — calls `analyze` and streams three progress phases

**Q&A and LLM sampling**
- "What is the capital of France?" — calls `smart-answer`, which delegates to the client's LLM via `ask`
- "Ask anything" — routes arbitrary questions through `smart-answer`

**Resources**
- "Read the server docs" — reads `docs://readme`
- "Look up user 42" — reads `user://42`

**Prompts**
- "Review my code" — invokes the `code-review` prompt with a code snippet
- "Help me debug this stack trace" — invokes the `debug` prompt with an error and optional context

---

## Example Responses

```
greet(name: "Alice")
→ "Hello, Alice!"

whoami()
→ "Your mctx user ID is: user_abc123. This ID is stable across all your devices and sessions."

calculate(operation: "multiply", a: 6, b: 7)
→ { "operation": "multiply", "a": 6, "b": 7, "result": 42 }

analyze(topic: "quantum computing")
→ [progress: 1/3] → [progress: 2/3] → [progress: 3/3]
→ "Analysis of "quantum computing" complete. Found 42 insights across 7 categories."

smart-answer(question: "What is the capital of France?")
→ "Question: What is the capital of France?\n\nAnswer: Paris."

Read URI: docs://readme
→ "Welcome to the example MCP server built with @mctx-ai/mcp..."

Read URI: user://42
→ { "id": "42", "name": "User 42", "joined": "2024-01-01", "role": "developer" }

code-review(code: "const x = eval(input)", language: "javascript")
→ "Please review this javascript for bugs, security issues, and improvements:..."

debug(error: "TypeError: Cannot read properties of undefined")
→ [user] "I'm seeing this error: TypeError: Cannot read..."
→ [assistant] "I will analyze the error and provide step-by-step debugging guidance."
```

---

## Getting Started

### Using as a Template

This repo is a GitHub template. Click **Use this template** on GitHub, then:

**1. Clone your new repo**

```bash
git clone https://github.com/your-username/your-repo.git
cd your-repo
```

**2. Run the setup script**

```bash
./setup.sh
```

`setup.sh` prompts for a project name and description, asks whether to keep the example code or start from a minimal skeleton, updates `package.json`, rewrites `README.md` with a clean starting point, installs dependencies, creates an initial git commit, and deletes itself.

**3. Start developing**

```bash
npm run dev
```

If you kept the examples, `src/index.ts` is unchanged — study the patterns and modify from there. If you started empty, you get a minimal skeleton with a single `hello` tool to build from.

### Development Commands

**Build**

```bash
npm run build
```

Bundles `src/index.ts` to `dist/index.js` using esbuild (minified ESM output).

**Dev server**

```bash
npm run dev
# Test environment variables during dev:
GREETING="Howdy" npm run dev
```

Runs parallel watch mode: esbuild rebuilds on source changes, mctx-dev hot-reloads the server on rebuild.

**Testing**

```bash
npm test                          # Run all tests
npm test -- --watch               # Watch mode
npm test src/index.test.ts        # Specific file
npm test -- -t "greet"            # Pattern match
```

**Linting and formatting**

```bash
npm run lint
npm run format
npm run format:check
```

### Environment Variables

**`GREETING`** — Customizes the greeting in the `greet` tool (default: `"Hello"`). Set `GREETING="Howdy"` to get `"Howdy, Alice!"`.

---

## Project Structure

```
src/index.ts        → Server implementation — all capabilities in one file
  ├─ Tools          → greet, whoami, calculate, analyze, smart-answer
  ├─ Resources      → docs://readme (static), user://{userId} (dynamic)
  ├─ Prompts        → code-review (single-message), debug (multi-message)
  └─ Export         → fetch handler for JSON-RPC 2.0 over HTTP

src/index.test.ts   → Tests for every tool, resource, and prompt
dist/index.js       → Bundled output (generated by esbuild, not committed on main)
```

---

## Deployment Model

**mctx does not run build commands.** It serves `dist/index.js` from the `release` branch — no `npm run build` at deploy time.

**`dist/` is gitignored on `main`.** The release pipeline (`.github/workflows/release.yml`) builds `dist/index.js` from source and commits it to `release` automatically. Source-only on `main`; built output on `release`.

**Deployment trigger:** mctx watches for `version` changes in `package.json` on the `release` branch. A version bump triggers a new deployment. A push with no version bump does not trigger deployment.

**Conventional commits determine the version bump:**

| Commit prefix | Bump |
|---|---|
| `feat!:` or `fix!:` | Major |
| `feat:` | Minor |
| Everything else | Patch |

This repo uses squash merging — PR title becomes the commit subject, so **PR titles must follow conventional commit format**.

Do not edit the `release` branch directly. Do not commit `dist/index.js` on `main`.

---

## Making Your MCP Server Discoverable

Three `package.json` fields and `README.md` determine how developers find your MCP server.

- **`description`** — Appears in the MCP Community Registry (truncates at ~100–150 chars) and on your mctx.ai page. Front-load the most important information.
- **`homepage`** — Clickable link on your public mctx.ai page. Point it at your GitHub repo or docs site.
- **`README.md`** — Becomes the documentation on your mctx.ai page and is indexed by Context7 for AI assistant discovery. Lead with what the MCP server does; the first ~4,000 characters are what AI assistants use to understand and recommend it.

---

## Learn More

- [`@mctx-ai/mcp`](https://github.com/mctx-ai/mcp) — Framework documentation and API reference
- [docs.mctx.ai](https://docs.mctx.ai) — Platform guides for deploying and managing your MCP servers
- [mctx.ai](https://mctx.ai) — Host your MCP server for free
- [MCP Specification](https://modelcontextprotocol.io) — The protocol spec this MCP server implements

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mctx-ai](https://github.com/mctx-ai)
- **Source:** [mctx-ai/example-mcp-server](https://github.com/mctx-ai/example-mcp-server)
- **License:** MIT
- **Homepage:** https://mctx.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mctx-ai-example-mcp-server
- Seller: https://agentstack.voostack.com/s/mctx-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.