Overview

An assistant requesting a shipment quote needs a named operation, an argument schema, and a result it can interpret. The Model Context Protocol (MCP) provides that connection between an AI application’s client and your application. Your service still owns the calculation, access decisions, and any effects.

Request Path

The AI application is the host. Its MCP client discovers tools and calls them with JSON arguments; your MCP server dispatches those calls to application operations:

AI host → MCP client → HTTP endpoint → typed operation

arkoren.dev/core/mcp defines immutable tools without depending on a protocol SDK. arkoren.dev/driver/mcp/mcpserver registers selected definitions with the official Go MCP SDK and returns an http.Handler. Your application mounts that handler and owns the listener, authentication, deadlines, and shutdown.

Serving tools does not require a model API key or a model conversation in your Go process. If your application needs to run the model itself, use Running Agents instead. MCP serving, LLM agents, and the documentation skill are separate tasks.

Typed Operations

Start with a narrow application operation rather than exposing arbitrary service methods. For a shipment quote, define its JSON argument and result shapes:

type QuoteRequest struct {
	WeightGrams int `json:"weight_grams"`
}

type Quote struct {
	PriceCents int `json:"price_cents"`
}

With quote as your existing func(context.Context, QuoteRequest) (Quote, error), import arkoren.dev/core/mcp and publish its tool definition:

tool := mcp.NewTool("shipping.quote", quote, func(action *mcp.ToolBuilder[QuoteRequest, Quote]) {
	action.Description("Quote domestic shipping in cents for a parcel's weight.")
	action.ReadOnly(true)
	action.OpenWorld(false)
})

Clients discover shipping.quote with object schemas using weight_grams and price_cents. Go types provide inferred schemas; explicit validation adds domain constraints. Tool names are static protocol identifiers, not per-user routes. Read-only and other annotations are descriptive hints, not permission checks.

The Tools guide completes this example with weight validation, output checks, registration, and focused tests. Its fragments keep error results visible while omitting routine propagation; complete functions and programs handle their errors.

Managed Serving

A definition becomes remotely accessible only when you explicitly register it with mcpserver.Builder.Tools and mount the endpoint. These managed tools receive typed input parsing, validation of encoded output, safe error mapping, panic recovery, and optional payload-free call telemetry.

The endpoint uses stateless Streamable HTTP, not a client-launched stdio command. It does not own an HTTP listener or retry handlers. Output validation happens after execution, so a failed result does not undo business effects.

Follow First Server for a complete loopback server and a real client discovery/call path. Before serving private operations or remote traffic, configure Securing MCP. Then use Capability Access to distinguish offering an operation from authorizing its selected records.

Diagnostic Tools

For inspecting an existing application, use Capture Setup rather than writing domain tools. Diagnostic factories return ordinary tool definitions; importing a package exposes nothing. Select registrations explicitly, attach application capture before startup, and follow the diagnostic privacy constraints.

Use Application Diagnosis for the inspection workflow and Diagnostic Tools for individual operation names and result boundaries.

The Arkoren CLI is an optional MCP client, not a second catalog or protocol. MCP resources, prompts, native tools, and other transports require the native SDK boundary; they do not gain managed protections automatically.

For declarations and adapter settings, see the core MCP API and MCP server API.