ftl-mcp

A WebAssembly-based implementation of the Model Context Protocol (MCP) for building secure, fast, deployable tools that plug in to any AI agent and run efficiently on almost any type of compute.

Quick Start

Writing a Tool

🦀 Rust Example

use ftl_sdk::{tool, ToolResponse};
use serde::Deserialize;
use schemars::JsonSchema;

#[derive(Deserialize, JsonSchema)]
struct EchoInput {
    /// The message to echo back to the caller, verbatim
    message: String
}

/// Echo the message back to the caller
#[tool]
fn echo_rs(input: EchoInput) -> ToolResponse {
    ToolResponse::text(format!("Echo: {}", input.message))
}

🟦 TypeScript Example

import { createTool, ToolResponse } from 'ftl-sdk'
import { z } from 'zod'

// Define the schema using Zod
const EchoInputSchema = z.object({
  message: z.string().describe('The message to echo back to the caller, verbatim')
})

// Derive TypeScript type from the schema
type EchoInput = z.infer<typeof EchoInputSchema>

const echo = createTool<EchoInput>({
  metadata: {
    name: 'echo_ts',
    title: 'Echo TS',
    description: 'Echo the message back to the caller',
    // Using Zod v4's native JSON Schema conversion
    inputSchema: z.toJSONSchema(EchoInputSchema)
  },
  handler: async (input) => {
    // Input is pre-validated
    return ToolResponse.text(`Echo: ${input.message}`)
  }
})

//@ts-ignore
addEventListener('fetch', (event: FetchEvent) => {
  event.respondWith(echo(event.request))
})

Why?

ftl-mcp enables you to build MCP-compatible toolkits that run as WebAssembly components on the wasmtime-based Spin framework. FTL toolkits can be natively deployed to extremely fast, globally distributed Akamai edge workers via Fermyon. They can also run on any WebAssembly-compatible host. Each tool executes within its own isolated sandbox with capability-based permissions. You can mix and match tools written in different source languages within a toolkit.

Architecture

MCP Client → Auth Gateway → MCP Gateway → [Tool Components]

Components

• Auth Gateway: MCP-compatible authentication layer using WorkOS AuthKit
• MCP Gateway: Implements the MCP protocol, routes requests to the appropriate tool component, and validates tool call arguments
• Tool Components: Individual WebAssembly components implementing specific functionality as MCP tools
• SDKs: TypeScript and Rust libraries for building tools

Run and use MCP tools

1. Configure your tools in spin.toml:

[variables]
tool_components = { default = "echo,calculator,weather" }

[[trigger.http]]
route = "/mcp"
component = "ftl-mcp-gateway"

[component.ftl-mcp-gateway]
source = { registry = "ghcr.io", package = "fastertools:ftl-mcp-gateway", version = "0.0.3" }
allowed_outbound_hosts = ["http://*.spin.internal"]
[component.ftl-mcp-gateway.variables]
tool_components = "{{ tool_components }}"

2. Build and run:

spin up --build

3. Test your deployment:

# List available tools
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"tools/call",
    "params": {
      "name": "echo",
      "arguments": {"message": "Hello, World!"}
    },
    "id": 2
  }'

4. Plug in to your MCP client.

{
  "mcpServers": {
    "ftl-tools": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "http"
    }
  }
}

Features

• Language Support: Build tools in TypeScript or Rust
• Schema Validation: Automatic input validation using JSON Schema
• Security: WebAssembly isolation with capability-based permissions
• Authentication: Optional JWT authentication with AuthKit integration
• Performance: Parallel tool execution and efficient routing
• Standards: Full MCP protocol compliance. Built on the Wasm component model.

SDKs

TypeScript SDK (ftl-sdk)

• Zero-dependency core with optional Zod integration
• Type-safe tool creation with createTool helper
• Automatic schema generation from Zod schemas

Rust SDK (ftl-sdk)

• Procedural macros for minimal boilerplate
• Automatic schema generation using schemars
• Native async/await support

Getting Started with Templates

Install the Spin templates:

spin templates install --dir .

Create a new MCP server:

spin new -t ftl-mcp-server my-server
cd my-server
spin add -t ftl-mcp-ts hello-tool
spin add -t ftl-mcp-rust greet-tool
# Update tool_components in spin.toml
spin build --up

See the templates/ directory for available templates and documentation.

Examples

See the examples/demo directory for complete examples:

• echo-ts/echo-rs: Basic echo tools
• calculator-ts: Advanced validation with Zod
• weather-ts/weather-rs: External API integration

License

Apache-2.0