MCP Sample Agent Tutorial

A Model Context Protocol (MCP) server that exposes tools, resources, and prompts for users and todos. Supports both stdio (local) and Streamable HTTP (cloud-ready) transports. This tutorial explains the project structure, how tools, resources, and prompts are built, and how to integrate with Cursor.

Prerequisites

• Node.js 18+
• npm or pnpm

Quick Start

npm install
npm run dev          # Run the MCP server (Streamable HTTP on port 3000)
npm run inspect      # Test in MCP Inspector

---

Project Structure

tc_mcp_III/
├── src/
│   ├── index.ts              # Entry point: Express + Streamable HTTP transport
│   ├── server.ts             # MCP server factory (createMCPServer)
│   ├── entities/
│   │   ├── user.entity.ts    # Zod schemas and types for users
│   │   └── todo.entity.ts    # Zod schemas and types for todos
│   ├── users/
│   │   └── userHandler.ts    # Business logic: create, fetch users
│   ├── tools/
│   │   └── users/
│   │       ├── createUserTool.ts   # MCP tool: create-user
│   │       └── fetchUsersTool.ts   # MCP tool: fetch-users
│   ├── resources/
│   │   ├── users/
│   │   │   └── usersResources.ts   # MCP resource: users (read-only)
│   │   └── todo/
│   │       ├── todoResources.ts   # MCP resources: todos, single-todo (template)
│   │       └── todoHandler.ts     # Fetches todos from dummyjson.com
│   └── prompts/
│       └── todos/
│           └── todosPrompts.ts    # MCP prompt: fetch-todo-item
├── users.json                # JSON "database" for users
├── .cursor/
│   └── mcp.json              # Cursor MCP configuration
├── package.json
└── tsconfig.json

Layer Responsibilities

| Layer | Purpose | |-------|---------| | index.ts | Bootstraps Express, creates server per request, connects Streamable HTTP transport | | server.ts | Factory createMCPServer() for stateless per-request servers | | entities/ | Shared schemas (Zod) and TypeScript types | | users/ | Domain logic (CRUD) independent of MCP | | tools/ | MCP tool definitions: wire schema + handler via registerXxx(server) | | resources/ | MCP resource definitions: read-only data exposed via URI | | prompts/ | MCP prompt templates for AI interactions |

---

Transport: Streamable HTTP

The server uses Streamable HTTP transport, making it suitable for cloud deployment (e.g., GCP Cloud Run). Each HTTP request gets a fresh MCP server instance (stateless pattern).

How It Works

1. Express app listens on PORT (default 3000)
2. All MCP traffic goes to the /mcp endpoint
3. For each request: create server → register tools/resources/prompts → connect transport → handle → close

// src/index.ts (simplified)
function getServer() {
    const server = createMCPServer();
    registerCreateUserTool(server);
    registerFetchUserTool(server);
    registerAllUsersResource(server);
    registerAllTodoResources(server);
    registerSingleTodoResource(server);
    registerFetchPrompt(server);
    return server;
}

app.all('/mcp', async (req, res) => {
    const server = getServer();
    const transport = new StreamableHTTPServerTransport();
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body ?? {});
    res.on('close', () => {
        server.close();
        transport.close();
    });
});

---

Server Factory (src/server.ts)

The server is created per request to support stateless HTTP:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function createMCPServer() {
    return new McpServer(
        { name: 'emi_mcp_server', version: '1.0.0' },
        {
            capabilities: {
                tools: {},
                prompts: {},
                resources: {},
                tasks: {}
            }
        }
    );
}

---

Registration Pattern

Tools, resources, and prompts use registration functions that accept a server instance. This allows a new server to be created per request and configured before use.

Example: fetch-users tool

import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

export function registerFetchUserTool(server: McpServer) {
    server.registerTool(
        'fetch-users',
        { title: '...', description: '...', inputSchema: fetchUserSchema },
        async (userSearch) => ({ content: [{ type: 'text', text: JSON.stringify(foundUsers) }] })
    );
}

---

Resources

Static Resources

| Resource | URI | Description | |----------|-----|-------------| | users | users://all | All users from users.json | | todos | todos://all | All todos from dummyjson.com API |

Resource Templates

| Resource | URI Template | Description | |----------|--------------|-------------| | single-todo | todos://{id}/single | Fetch a single todo by ID |

Resource templates appear in the Templates section of the MCP Inspector. To read a single todo, request e.g. todos://5/single.

Return format: { contents: [{ uri: string, text: string }] }

---

Prompts

Prompts are reusable templates for AI interactions. In Cursor, type / in the chat to see available prompts.

| Prompt | Args | Description | |--------|------|-------------| | fetch-todo-item | id (number) | Generates a prompt to fetch a todo by ID |

Example: /fetch-todo-item with id: 1 → "go and get a todo item based on 1"

---

Adding the Server to Cursor

Option A: Local (stdio via mcp-remote)

If running the HTTP server locally, use mcp-remote to proxy:

{
  "mcpServers": {
    "tc_mcp_iii": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"],
      "cwd": "C:\\code\\MCP\\tc_mcp_III"
    }
  }
}

Option B: Direct URL (if Cursor supports it)

{
  "mcpServers": {
    "tc_mcp_iii": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Option C: Cloud deployment

For a server deployed on Cloud Run or similar:

{
  "mcpServers": {
    "tc_mcp_iii": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR-SERVICE.run.app/mcp"]
    }
  }
}

---

Testing with MCP Inspector

Connect via URL (Streamable HTTP)

1. Terminal 1 – Start the server:

   npm run dev

1. Terminal 2 – Launch Inspector and connect to URL:

   npx @modelcontextprotocol/inspector --connect http://localhost:3000/mcp

1. In the Inspector UI, select streamable-http as the transport and enter http://localhost:3000/mcp if prompted.

Connect via stdio (legacy)

The npm run inspect script spawns the server as a child process. For Streamable HTTP testing, use the two-terminal approach above.

---

Available Tools

| Tool | Description | Required params | |------|-------------|-----------------| | create-user | Create a new user | name, email, phone (address optional) | | fetch-users | Search users | name, email, phone |

Available Resources

| Resource | URI | Description | |----------|-----|-------------| | users | users://all | All users from users.json | | todos | todos://all | All todos from dummyjson.com | | single-todo | todos://{id}/single | Single todo by ID (template) |

Available Prompts

| Prompt | Args | Description | |--------|------|-------------| | fetch-todo-item | id (number) | Generate a prompt to fetch a todo by ID |

---

Cloud Deployment (GCP Cloud Run)

The server is ready for cloud deployment:

1. Build & deploy:

   gcloud run deploy tc-mcp-server --source .

1. Environment: Set PORT (Cloud Run uses 8080 by default).

1. Client config: Point Cursor or Inspector to https://YOUR-SERVICE.run.app/mcp.

1. Auth: Use gcloud run services proxy for local clients, or OIDC/IAM for production.

See Host MCP servers on Cloud Run for details.

---

Troubleshooting

| Issue | Solution | |-------|----------| | Tools not showing | Ensure all registerXxx(server) are called in getServer() | | "Already connected to a transport" | Use per-request server pattern: create server in handler, call server.close() on response close | | Inspector URL not connecting | Start server with npm run dev first, then --connect http://localhost:3000/mcp | | Prompts not in Cursor | Type / in chat; ensure server is configured and connected | | Single-todo not in Resources list | It's a template—check the Templates section, or read todos://1/single directly | | Transport type error | Use transport as Transport with exactOptionalPropertyTypes |

---

References

• Model Context Protocol
• MCP TypeScript SDK
• Host MCP servers on Cloud Run
• Cursor MCP Docs