tsed-mcp-server

# Ts.ED MCP Server `@tsed/platform-mcp` turns Ts.ED providers into MCP tools, resources and prompts. Handlers run inside the Ts.ED injector, so they reuse the application's services. Read [the API reference](references/api.md) for option tables, resources, prompts and error payloads, and [the standalone and clients reference](references/standalone-and-clients.md) for stdio servers and client registration, and [the gateway and OAuth reference](references/gateway-and-oauth.md) for proxying a third-party MCP server and protecting the endpoint. This skill is about the MCP server your application exposes; the MCP server shipped by the Ts.ED CLI belongs to the sibling skill `tsed-cli`. ## 1. Install and mount the endpoint Run `npm install @tsed/platform-mcp`, then import it in `Server.ts`: ```typescript import "@tsed/platform-express"; import "@tsed/platform-mcp"; import {Configuration} from "@tsed/di"; import {OrderTools} from "./mcp/OrderTools.js"; import {docsResource} from "./mcp/docsResource.js"; @Configuration({ mcp: { path: "/mcp", name: "orders", version: "1.0.0", tools: [OrderTools], resources: [docsResource] } }) export class Server {} ``` 1. The side-effect import registers the module; without it no route is mounted. 2. The module mounts `POST <path>` (default `/mcp`). The transport is stateless: a new MCP server is created per request. 3. `name` and `version` fall back to the root `name` / `version` configuration, then to `tsed-mcp` / `0.0.0`. 4. Set `enabled: false` to skip an endpoint; use an array (`mcp: [{name, path, tools}, ...]`) to expose several independent servers. ## 2. Register every provider explicitly A decorator or a `define*` call alone exposes nothing. List each decorated class and each `define*` token in the `tools`, `resources` or `prompts` array of every server that should expose it. A class contributes all of its decorated methods of that kind. ## 3. Write a tool with decorators ```typescript import {Injectable, inject} from "@tsed/di"; import {Tool} from "@tsed/platform-mcp"; import {Description, Property, Required, Returns} from "@tsed/schema"; import {OrdersService} from "../services/OrdersService.js"; class GetOrderInput { @Required() @Description("Order identifier") id: string; } class OrderResult { @Property() status: string; } @Injectable() export class OrderTools { protected orders = inject(OrdersService); @Tool("get-order") @Description("Returns one order by id") @Returns(200, OrderResult) async getOrder(input: GetOrderInput) { return this.orders.get(input.id); } } ``` 1. The input schema comes from the **class** type of the first parameter. Interfaces and inline object types produce no schema. 2. The output schema comes from `@Returns(200, Model)`. Omit it and no `outputSchema` is advertised. 3. The description comes from `@Description`; the name from `@Tool(name)` or the method name. Pass `title`, `annotations` or explicit schemas as `@Tool(name, {...})`. 4. Return a plain object or model: Ts.ED serializes it into both `content` (JSON text) and `structuredContent`. Return a full MCP result (`{content: [...]}`) only for custom content. 5. Write model and parameter descriptions for an LLM reader: they are the tool's only documentation. Model decorators are covered by the sibling skill `tsed-models`. ## 4. Write a tool with the functional API ```typescript import {inject} from "@tsed/di"; import {defineTool} from "@tsed/platform-mcp"; import {s} from "@tsed/schema"; import {OrdersService} from "../services/OrdersService.js"; export const cancelOrderTool = defineTool({ name: "cancel-order", description: "Cancels an order that is not shipped yet", inputSchema: s.object({id: s.string().required().description("Order identifier")}), outputSchema: s.object({status: s.string().required()}), async handler({id}) { return {status: await inject(OrdersService).cancel(id)}; } }); ``` - `defineTool` returns a DI token; add it to `mcp.tools`. Call `inject()` inside the handler, not at module top level. - Resources (`@Resource` / `defineResource`) and prompts (`@Prompt` / `definePrompt`) follow the same two styles; see the reference. ## 5. Handle errors - Handlers never throw to the transport. A thrown error is logged (`MCP_TOOL_ERROR`, `MCP_RESOURCE_ERROR`, `MCP_PROMPT_ERROR`) and converted to a payload. - A tool error returns `isError: true` with `structuredContent: {status_code, code, message, tool}`. - `code` is `E_MCP_<KIND>_<ERROR_NAME>` when the error has both `name` and `status` (any `@tsed/exceptions` class, e.g. `NotFound` gives `E_MCP_TOOL_NOT_FOUND`); otherwise `E_MCP_<KIND>_ERROR`. - Throw `@tsed/exceptions` errors (sibling skill `tsed-exceptions`) with messages safe to show to a model; the message is returned verbatim. Arguments that violate the input schema are rejected by the MCP SDK before the handler runs. ## 6. Run a standalone server Use `mcpServerConnect("stdio" | "streamable-http")` from `@tsed/platform-mcp/cli` once the injector is loaded. It reads a single `mcp` configuration object (an array throws). Full scripts are in [the reference](references/standalone-and-clients.md). - With `stdio`, stdout belongs to the protocol. Never call `console.log`; send diagnostics to stderr. The helper stops the Ts.ED logger before connecting. - `streamable-http` serves `POST /mcp` on `PORT` (default `3000`), ignores `mcp.path`, and needs `express` installed. ## 7. Test Unit-test a tool through its token, inside `PlatformTest.create()` / `PlatformTest.reset()` (from `@tsed/platform-http/testing`): ```typescript const tool = inject<any>(cancelOrderTool); const result = await tool.handler({id: "42"}, {} as any); expect(result.structuredContent).toEqual({status: "cancelled"}); ``` A failing handler resolves with `result.isError === true`; it does not reject. For an end-to-end check, bootstrap with `PlatformTest.bootstrap(Server)` and `POST /mcp` a JSON-RPC body with SuperTest (full example in the reference). Mocking services follows the sibling skill `tsed-testing`. ## 8. Register the server in a client Add the HTTP endpoint (`{"type": "http", "url": "http://localhost:8083/mcp"}`) or the stdio command to `.mcp.json` under `mcpServers` for Claude Code, or to a `[mcp_servers.<name>]` table in Codex `config.toml`. Exact snippets are in [the reference](references/standalone-and-clients.md#register-in-clients). ## 9. Proxy a third-party MCP server and protect the endpoint Add `upstream` to an `mcp` entry to serve a third-party MCP server (Streamable HTTP, SSE, or a stdio process such as an `npx` server) through the Ts.ED endpoint, and `auth` to protect the entry with an OAuth authorization server. Forward the caller's token with the `${OAUTH_TOKEN}` placeholder in the upstream `headers`, or `args`/`env` for stdio. Option tables and startup errors are in [the reference](references/gateway-and-oauth.md). ```typescript mcp: [ { path: "/mcp/directus", auth: {issuer: "https://auth.example.com", resource: "https://api.example.com/mcp/directus", requiredScopes: ["mcp:read"]}, upstream: {type: "http", url: "https://directus.example.com/mcp", headers: {Authorization: "Bearer ${OAUTH_TOKEN}"}} } ]; ``` ## Do not - Do not expect `@Tool`, `@Resource` or `@Prompt` to auto-register; list the class in the `mcp` configuration. - Do not reuse a tool, resource or prompt name: the DI token is derived from the name (`MCP:TOOL:<name>`), so two definitions collide. - Do not write to stdout in a stdio server, including from child processes and third-party loggers. - Do not leave the HTTP endpoint unauthenticated: tools run with the application's privileges. Use the `auth` option (OAuth, or a custom check such as an API key with `auth.preAuth`) rather than a global middleware testing the path. - Do not write `${OAUTH_TOKEN}` inside a template literal (backticks): it is a plain-string placeholder resolved per request, not a JavaScript interpolation. - Do not declare several upstreams in one `mcp` entry; use one entry per upstream. - Do not import from `@tsed/common` or from `@modelcontextprotocol/sdk`; the package uses `@modelcontextprotocol/server` and `@modelcontextprotocol/node`. ## Pitfalls - Tool missing from `tools/list`: the class or token is not in `mcp.tools` of that server, `@tsed/platform-mcp` is not imported, or the class lacks `@Injectable()`. - Empty input schema: the parameter type is an interface, or its properties have no `@tsed/schema` decorator. - A class-based `@Prompt` gets no arguments schema from its parameter; pass `argsSchema` in the decorator options. - Only `POST <path>` is served and the transport is stateless with JSON responses; `GET` and `DELETE` on the path answer `405` with `Allow: POST`. Clients that require sessions or a `GET` event stream are not served by the HTTP module. - `401` on every call in introspection mode: the authorization server does not return `aud` for the endpoint `resource`. Configure resource indicators on the authorization server, or set `audience: false`. - Offline mode rejects valid-looking JWTs: the token is not an RFC 9068 access token (`typ: at+jwt` with `iss`, `exp`, `aud`, `sub`, `iat`, `jti`, `client_id`). Use introspection or a custom `verifier`. - Upstream tools missing from `tools/list`: the upstream is unreachable (see the `MCP_GATEWAY_UPSTREAM_ERROR` log) or a local tool has the same name (`MCP_GATEWAY_COLLISION`). - In a standalone script, `mcpServerConnect("stdio")` fails with `logger(...).stop is not a function` unless a `@tsed/logger` instance is attached to the injector (`attachLogger($log)`). ## Checklist - `@tsed/platform-mcp` is imported and every tool, resource and prompt is listed in `mcp`. - Each tool has a name, an LLM-readable description, a class or `s.object` input schema, and an output schema. - Handlers resolve services with `inject()` and throw `@tsed/exceptions` errors. - A test calls each tool handler, including one failing path. - The endpoint is protected, or bound to a trusted network. - stdio entry points print nothing on stdout; the client configuration was tried with `npx @modelcontextprotocol/inspector`. Further reading: https://tsed.dev/docs/mcp.md.