From 02ff337f14cb1b4510e7b26a07f71bf41bf5bf1b Mon Sep 17 00:00:00 2001 From: bethh0rn Date: Tue, 17 Jun 2025 16:14:10 +0200 Subject: [PATCH 1/2] Edit: Custom MCP server extensions --- .../custom-mcp-tools-resources.mdx | 43 ++++++++----------- 1 file changed, 18 insertions(+), 25 deletions(-) diff --git a/docs/model-context-protocol/custom-mcp-tools-resources.mdx b/docs/model-context-protocol/custom-mcp-tools-resources.mdx index b483246e..75f9ad40 100644 --- a/docs/model-context-protocol/custom-mcp-tools-resources.mdx +++ b/docs/model-context-protocol/custom-mcp-tools-resources.mdx @@ -1,16 +1,13 @@ --- title: Custom MCP Server Extensions --- -# Adding custom MCP tools & resources +# Custom MCP server extensions +Developers can now use Speakeasy to augment their MCP servers by adding extensions for additional custom tools, resources, and prompts. +## Setting up MCP extensions -A Speakeasy SDK developer can now augment their MCP server by adding extensions for additional custom tools, resources, and prompts. - -### Setting Up MCP Extensions - -To do so, a developer must create a new file under the `mcp-server` directory called `server.extensions.ts`. The file should expose the following function contract exactly. -This function can be used to register custom tools, resources, and prompts on to generated MCP server. +To set up MCP extensions, create a new file under the `mcp-server` directory and name it `server.extensions.ts`. The file should expose the following function contract exactly. ```typescript server.extensions.ts import { Register } from "./extensions.js"; @@ -22,19 +19,17 @@ export function registerMCPExtensions(register: Register): void { } ``` -After adding this file and defining the custom tools and resources, execute `speakeasy run`. +This function can be used to register custom tools, resources, and prompts on a generated MCP server. + +After adding the `server.extensions.ts` file and defining the custom tools and resources, execute `speakeasy run`. -### Building and Registering Custom Tools +## Building and registering custom MCP tools -Below is an example of a custom [MCP tool](https://modelcontextprotocol.io/docs/concepts/tools) that fetches files from public GitHub repositories. -This custom tool is then registered in the `registerMCPExtensions` function. -One can opt to define their custom /resources in separate files or define everything within the `server.extensions.ts` file. +Below is an example of a custom [MCP tool](https://modelcontextprotocol.io/docs/concepts/tools) that fetches files from public GitHub repositories. This custom tool is then registered in the `registerMCPExtensions` function. -The most important thing is to ensure that the tool fits the `ToolDefinition` type exposed by Speakeasy. -Notice this tool has `args` defined as a Zod schema, tools can also have no arguments defined. -Every tool also defines a `tool` method for execution. +You can define your custom `/resources` in separate files or define them all in the `server.extensions.ts` file. The most important thing is to ensure that the tool fits the `ToolDefinition` type exposed by Speakeasy. Although this tool has `args` defined as a Zod schema, tools can also have no arguments defined. Every tool also defines a `tool` method for execution. -Speakeasy exposes a `formatResult` utility function from `tools.ts` that can be used to ensure the result ends up in the proper MCP format when returned. Using this function is optional as long as the return matches the required type. +Speakeasy exposes a `formatResult` utility function from `tools.ts` that you can use to ensure the result is returned in the proper MCP format. Using this function is optional as long as the return matches the required type. ```typescript custom/getGithubFileTool.ts import { z } from "zod"; @@ -96,23 +91,21 @@ export function registerMCPExtensions(register: Register): void { } ``` -### Building and Registering Custom Resources +## Building and registering custom MCP resources -An [MCP Resource](https://modelcontextprotocol.io/docs/concepts/resources) represents any kind of data source that an MCP server can make available to clients. Each resource is identified by a unique URI and can contain either text or binary data. +An [MCP resource](https://modelcontextprotocol.io/docs/concepts/resources) represents any kind of data source that an MCP server can make available to clients. Each resource is identified by a unique URI and can contain either text or binary data. Resources can encompass a variety of things, including: - File contents (local or remote) - Database records - Screenshots and images - Static API responses -- And more -Below is an example of a custom MCP Resource that embeds a local PDF file as a resource into an MCP server. +Below is an example of a custom MCP resource that embeds a local PDF file as a resource in an MCP server. -The custom resource must fit the `ResourceDefinition` or `ResourceTemplateDefinition` type exposed by Speakeasy. -A resource must define a `read` function for reading data from the defined URI. +The custom resource must fit the `ResourceDefinition` or `ResourceTemplateDefinition` type exposed by Speakeasy and define a `read` function for reading data from the defined URI. -Speakeasy exposes a `formatResult` utility function from `resources.ts` that can be used to ensure the result ends up in the proper MCP format when returned. Using this function is optional as long as the return matches the required type. +Speakeasy exposes a `formatResult` utility function from `resources.ts` that you can use to ensure the result is returned in the proper MCP format. Using this function is optional, as long as the return matches the required type. ```typescript custom/aboutSpeakeasyResource.ts import { formatResult, ResourceDefinition } from "../resources.js"; @@ -153,9 +146,9 @@ export function registerMCPExtensions(register: Register): void { } ``` -### Building and Registering Custom Prompts +## Building and registering custom MCP prompts -An [MCP Prompt](https://modelcontextprotocol.io/docs/concepts/prompts) allows for creating reusable prompt templates and workflows for the MCP. +You can use [MCP prompt](https://modelcontextprotocol.io/docs/concepts/prompts) to create reusable prompt templates and workflows for MCP. ```typescript custom/customPrompts.ts import { z } from "zod"; From 90b6b7a4b46ebd77ed26f75994167aa52adafbe0 Mon Sep 17 00:00:00 2001 From: bethh0rn Date: Sun, 22 Jun 2025 12:24:17 +0200 Subject: [PATCH 2/2] Edit: Custom MCP server extensions --- docs/model-context-protocol/custom-mcp-tools-resources.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/model-context-protocol/custom-mcp-tools-resources.mdx b/docs/model-context-protocol/custom-mcp-tools-resources.mdx index 75f9ad40..6c094704 100644 --- a/docs/model-context-protocol/custom-mcp-tools-resources.mdx +++ b/docs/model-context-protocol/custom-mcp-tools-resources.mdx @@ -7,7 +7,7 @@ Developers can now use Speakeasy to augment their MCP servers by adding extensio ## Setting up MCP extensions -To set up MCP extensions, create a new file under the `mcp-server` directory and name it `server.extensions.ts`. The file should expose the following function contract exactly. +To set up MCP extensions, create a new file under the `mcp-server` directory and name it `server.extensions.ts`. The file should expose the following function contract exactly: ```typescript server.extensions.ts import { Register } from "./extensions.js"; @@ -29,7 +29,7 @@ Below is an example of a custom [MCP tool](https://modelcontextprotocol.io/docs/ You can define your custom `/resources` in separate files or define them all in the `server.extensions.ts` file. The most important thing is to ensure that the tool fits the `ToolDefinition` type exposed by Speakeasy. Although this tool has `args` defined as a Zod schema, tools can also have no arguments defined. Every tool also defines a `tool` method for execution. -Speakeasy exposes a `formatResult` utility function from `tools.ts` that you can use to ensure the result is returned in the proper MCP format. Using this function is optional as long as the return matches the required type. +Speakeasy exposes a `formatResult` utility function from `tools.ts` that you can use to ensure the result is returned in the proper MCP format. Using this function is optional, as long as the return matches the required type. ```typescript custom/getGithubFileTool.ts import { z } from "zod"; @@ -148,7 +148,7 @@ export function registerMCPExtensions(register: Register): void { ## Building and registering custom MCP prompts -You can use [MCP prompt](https://modelcontextprotocol.io/docs/concepts/prompts) to create reusable prompt templates and workflows for MCP. +You can use [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts) to create reusable prompt templates and workflows for MCP. ```typescript custom/customPrompts.ts import { z } from "zod";