API Reference¶

Server¶

func New(cfg config.Config) (*Server, error)
func (s *Server) Run(ctx context.Context, transport mcp.Transport) error
func (s *Server) MCPServer() *mcp.Server
func (s *Server) ListTools() []*mcp.Tool

Config¶

type Config struct {
  Index    handlers.Index
  Docs     handlers.Store
  Runner   handlers.Runner
  Executor handlers.Executor // optional

  Toolsets      handlers.ToolsetRegistry // optional (empty registry is valid)
  Skills        handlers.SkillRegistry   // optional (empty registry is valid)
  SkillDefaults handlers.SkillDefaults

  Refresher handlers.Refresher // optional backend refresh

  Providers        ProvidersConfig
  ProviderRegistry *provider.Registry // optional override
  Middleware       middleware.Config

  NotifyToolListChanged           bool
  NotifyToolListChangedDebounceMs int
}

Interface Contracts¶

• Transport: thread-safe; Serve honors context; Close is idempotent.
• Backend: thread-safe; ListTools/Execute honor context; streaming backends must return non-nil channel when err is nil.
• ToolProvider: thread-safe; Handle honors context; streaming providers must return non-nil channel when err is nil.

Transport¶

The transport layer is in internal/transport:

// Transport interface for MCP protocol transports
type Transport interface {
  Name() string
  Info() Info
  Serve(ctx context.Context, server Server) error
  Close() error
}

// Info describes a transport instance
type Info struct {
  Name string
  Addr string
  Path string
}

Available transports¶

StreamableHTTPConfig¶

type StreamableHTTPConfig struct {
  Host              string        // Network interface (default: "0.0.0.0")
  Port              int           // TCP port (required)
  Path              string        // Endpoint path (default: "/mcp")
  ReadHeaderTimeout time.Duration // Header read timeout (default: 10s)
  TLS               TLSConfig     // HTTPS configuration
  Stateless         bool          // Disable session management
  JSONResponse      bool          // Prefer JSON over SSE streaming
  SessionTimeout    time.Duration // Idle session cleanup
}

type TLSConfig struct {
  Enabled  bool
  CertFile string
  KeyFile  string
}

Toolruntime integration¶

When built with -tags toolruntime, execute_code is backed by a toolexec/runtime runtime. The runtime selects a profile at startup:

• dev profile: unsafe subprocess backend (default).
• standard profile: Docker sandbox by default or WASM when selected.
• METATOOLS_DOCKER_IMAGE overrides the sandbox image name.
• METATOOLS_WASM_ENABLED=true enables the WASM backend (wazero).
• METATOOLS_RUNTIME_BACKEND=wasm selects WASM for the standard profile.

MCP tool I/O types¶

These are exported in pkg/metatools:

• SearchToolsInput / SearchToolsOutput
• ListToolsInput / ListToolsOutput
• ListNamespacesInput / ListNamespacesOutput
• DescribeToolInput / DescribeToolOutput
• ListToolExamplesInput / ListToolExamplesOutput
• RunToolInput / RunToolOutput
• RunChainInput / RunChainOutput
• ExecuteCodeInput / ExecuteCodeOutput
• ListToolsetsInput / ListToolsetsOutput
• DescribeToolsetInput / DescribeToolsetOutput
• ListSkillsInput / ListSkillsOutput
• DescribeSkillInput / DescribeSkillOutput
• PlanSkillInput / PlanSkillOutput
• RunSkillInput / RunSkillOutput

Notes: - SearchToolsInput/ListNamespacesInput accept limit + cursor. - SearchToolsOutput/ListNamespacesOutput return nextCursor when more data exists.

Error codes¶

Metatools surfaces standardized error codes (strings), including:

• tool_not_found
• no_backends
• validation_input
• validation_output
• execution_failed
• stream_not_supported
• chain_step_failed
• cancelled
• timeout
• internal