Speakeasy Logo
Skip to Content
DocumentationAgent ToolsGenerate Server

Generate Server

Learn how to build MCP servers from your API specifications using Speakeasy for production-ready servers with extensive customization options.

Getting started with Speakeasy

To build an MCP server using Speakeasy:

  1. Install the Speakeasy CLI:

  2. Generate a TypeScript SDK:

  3. Enable MCP server generation in your .speakeasy/gen.yaml:

  4. Regenerate your SDK with MCP server:

This creates a new src/mcp-server directory with all the MCP server code and adds installation instructions to your README.

Server configuration

Configure your MCP server in your MCP client (like Claude Desktop):

For local development:

Advanced configuration

Specify scopes at runtime

When starting the MCP server, you can specify which scopes to include:

This example configuration only mounts tools tagged with the read scope, creating a read-only server.

Specify individual tools

You can further limit the subset of tools mounted on an MCP server by specifying individual tool names:

Distribution methods

Speakeasy generates MCP servers that can be published and distributed as npm packages or used directly with npx. This allows you to:

  • Share tools across teams
  • Deploy to different environments
  • Distribute to external users
  • Version and maintain your MCP servers independently

Best practices

When building MCP servers with Speakeasy:

  1. Use clear OpenAPI documentation - Well-documented APIs generate better MCP tools
  2. Leverage the x-speakeasy-mcp extension - Customize tool names, descriptions, and scopes
  3. Implement proper error handling - Ensure your API returns meaningful error messages
  4. Test thoroughly - Verify your MCP server works with different clients
  5. Version your APIs - Use semantic versioning for your OpenAPI specifications
  6. Monitor performance - Track usage and performance of your MCP tools

Next steps

Having set up your MCP server with Speakeasy, explore these additional capabilities:

Last updated on