Smithy MCP Server

Overview

This MCP server gives an AI assistant accurate, source-backed answers about Smithy. It retrieves semantic matches from the official Smithy documentation through an Amazon Bedrock Knowledge Base, and exposes the published Markdown directly for browsing and full-document reads. Point any MCP client at one HTTPS endpoint and start asking.

Stateless MCP Streamable HTTP. Send JSON-RPC 2.0 requests to this URL.

Add to your assistant

Pick your tool. Kiro supports a real one-click install; Claude Code and Codex install with a single terminal command. The raw JSON / TOML config is shown alongside each as a fallback.

{
  "mcpServers": {
    "smithy": {
      "url": "https://smithymcp.com/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

claude mcp add --transport http smithy https://smithymcp.com/mcp

claude mcp list

codex mcp add smithy --url https://smithymcp.com/mcp

[mcp_servers.smithy]
url = "https://smithymcp.com/mcp"

{
  "mcpServers": {
    "smithy-docs": {
      "url": "https://smithymcp.com/mcp",
      "transport": "http"
    }
  }
}

Available Tools

search_smithy_docs

Search the Smithy documentation with semantic search powered by the Bedrock Knowledge Base.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_smithy_docs",
    "arguments": {
      "query": "How do I define a service?",
      "max_results": 5
    }
  },
  "id": 1
}

Parameters:

• query (string, required): Search query, 1–2,000 characters.
• max_results (number, optional): 1–10, default 5.

read_smithy_doc

Read the full content of one Smithy documentation file.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_smithy_doc",
    "arguments": {
      "file_path": "quickstart.md"
    }
  },
  "id": 2
}

Parameters:

• file_path (string, required): Relative path below smithy-docs/; traversal is rejected.

list_smithy_topics

List every available Smithy documentation file.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_smithy_topics",
    "arguments": {}
  },
  "id": 3
}

Pair it with the Smithy Language Server

This server answers questions about Smithy. For live feedback while you write a .smithy model — diagnostics, hover, completion, go-to-definition — run the official Smithy Language Server (LSP) in your editor. The two work well together: the LSP keeps your model valid as you type, and this MCP server explains the concepts behind the rules.

1. Get the language server

Install the Smithy extension for VS Code (it bundles and launches the language server for you), or run the server directly for another editor:

# Run the Smithy Language Server (Java 17+ on PATH)
# Coursier is the simplest launcher:
cs launch software.amazon.smithy:smithy-language-server:latest.release

The VS Code Marketplace extension is the easiest path and needs no manual launch; the command above is for editors that speak LSP directly (Neovim, Emacs, Zed, …).

2. Point your editor at it

Most editors auto-detect a Smithy project from a smithy-build.json at the workspace root. A minimal one:

{
  "version": "1.0",
  "sources": ["model"]
}

Then a model file the language server will check as you edit it:

// model/weather.smithy
$version: "2"

namespace example.weather

/// Provides weather forecasts.
service Weather {
    version: "2006-03-01"
    operations: [GetForecast]
}

operation GetForecast {
    input := {
        @required
        city: String
    }
    output := {
        summary: String
        highC: Integer
    }
}

Save it and the language server reports unknown shapes, missing traits, and syntax errors inline. When it flags something you do not understand, ask your assistant — it calls this MCP server to explain the rule.

Example prompts

Once configured, ask your assistant things like:

• “Search the Smithy docs for how to define a service.”
• “How do resource shapes and their lifecycle operations work in Smithy?”
• “My model has @pattern on an integer — why is the LSP complaining?”
• “Show me an example of applying a custom trait.”

Architecture

• AWS Lambda — serverless compute for the MCP server.
• Bedrock Knowledge Base — semantic search over S3 Vectors storage.
• CloudFront + WAF — global CDN, TLS, and per-IP rate limiting.
• S3 — documentation storage and vector embeddings.

Documentation is refreshed from smithy-lang/smithy weekly, then re-indexed.

Resources

• Smithy documentation
• Smithy Language Server
• Model Context Protocol
• GitHub repository