EncDotNet.S100.Mcp
EncDotNet.S100.Mcp hosts the S-100 Model Context Protocol (MCP) tools from
EncDotNet.S100.Mcp.Tools, so an AI
agent can query loaded datasets. It serves them over Streamable HTTP, through
an in-process ASP.NET Core Kestrel listener, or over stdio. It has no UI
dependency. SoundCharts and s100 mcp serve both use it, and you can host it
in your own process.
For the tools, their parameters and how to connect a client, see the MCP server guide.
Install
This package isn't published to NuGet. Add a project reference:
<ProjectReference Include="path/to/src/EncDotNet.S100.Mcp/EncDotNet.S100.Mcp.csproj" />
Serve datasets over HTTP
S100McpServer serves the tools for an IDatasetCatalog, the set of datasets
the tools can see. FileDatasetCatalog is a ready-made catalog built from
dataset files:
using System.Net;
using EncDotNet.S100.Datasets.Pipelines;
using EncDotNet.S100.Datasets.Pipelines.Catalog;
using EncDotNet.S100.Mcp;
string path = args[0];
string spec = DatasetPipelineFactory.DetectProductSpec(path)
?? throw new InvalidOperationException($"Couldn't detect the product of {path}.");
var catalog = FileDatasetCatalog.Build(
[new FileDatasetInput(new DatasetId(Path.GetFileNameWithoutExtension(path)), spec, path)]);
await using var server = new S100McpServer(catalog, new S100McpServerOptions
{
BindAddress = IPAddress.Loopback,
Port = 0, // let the operating system pick a free port
});
await server.StartAsync();
Console.WriteLine($"MCP endpoint: {server.Endpoint}");
await Task.Delay(Timeout.Infinite);
The server maps one Streamable HTTP endpoint at the root path, so
server.Endpoint is http://127.0.0.1:<port>/. Connect any MCP client that
supports Streamable HTTP, such as the official ModelContextProtocol client
or mcp-inspector.
A host with its own live set of datasets, such as a viewer, implements
IDatasetCatalog instead of using FileDatasetCatalog. See
IDatasetCatalog.
Server options
S100McpServerOptions property |
Default | Description |
|---|---|---|
BindAddress |
IPAddress.Loopback |
The address to listen on. |
Port |
0 |
The TCP port. 0 lets the operating system pick one; read it from S100McpServer.Port. |
MaxConcurrentConnections |
16 |
A soft cap on concurrent sessions. Extra connections are still accepted, but ConnectionCount reports them so the host can refuse or throttle. |
IdleTimeout |
10 minutes | How long an idle session is kept. |
AdditionalTools |
null |
Host tools to serve alongside the built-in tools. See Add host tools. |
PassageRoutes |
null |
The host's routes, so check_route can check a route as well as a polyline. |
Toolsets |
null (all) |
The toolsets to serve. See Toolsets. |
Server members
S100McpServer member |
Description |
|---|---|
StartAsync, StopAsync |
Start and stop the listener. Both do nothing if the server is already in that state. |
IsRunning, Port, Endpoint |
The listener's state. Port and Endpoint are null until it starts. |
ConnectionCount |
The number of open MCP connections. |
StateChanged |
Raised when the server starts or stops. |
ConnectionsChanged |
Raised when ConnectionCount changes. |
DisposeAsync |
Stops the server. |
The constructor takes the catalog, the options and an optional
ILoggerFactory. SoundCharts passes its own logger factory so MCP requests
appear in its logs.
Serve datasets over stdio
S100McpStdioHost serves the same tools over standard input and output, for a
client that starts your process itself:
await S100McpStdioHost.RunAsync(catalog);
It runs until standard input closes or the cancellation token is cancelled.
Standard output carries the protocol, so the host sends all logging to standard
error. Don't write to Console.Out from your own code while it runs.
Built-in tools
S100McpTools.Create(catalog) returns the built-in tools, which
S100McpServer and S100McpStdioHost serve unless the selected toolsets leave them out. They only read the catalog:
list_datasets, describe_feature, describe_feature_type, sample,
find_at, identify_features, nearest_features, query_features,
count_features, search_features, list_specs, list_time_steps and
check_route.
Query tools in the MCP server guide describes each one.
Toolsets
Every tool belongs to one toolset, so a host can serve only the tools a task
needs: each tool's description takes room in an agent's context. The names are
constants on McpToolsets, such as McpToolsets.Query and McpToolsets.Routes;
McpToolsets.All lists them with a summary, and McpToolsets.Profiles names
sets of them, such as route-planning.
- Declare a tool's toolset where you create it:
McpToolsets.Assign(McpToolsets.Routes, tool), or for a list,McpToolsets.Assign(McpToolsets.Routes, tools). The built-in, session, Library and tide tools already declare theirs. The toolset is kept in the tool's in-process metadata, so it adds nothing totools/list. - Select toolsets with
S100McpServerOptions.Toolsets, or thetoolsetsargument ofS100McpStdioHost.RunAsync;nullserves them all.McpToolsets.TryParsereads a comma-separated list of names and profiles. McpToolsets.Select(tools, toolsets)does the selecting, and throws if a tool declares no toolset. Call it yourself when you host the tools another way.
Choose toolsets lists the toolsets and their sizes.
Add host tools
Pass extra McpServerTool instances in S100McpServerOptions.AdditionalTools,
or as the additionalTools argument of S100McpStdioHost.RunAsync. Their names
must not match a built-in tool, and each must declare its toolset (see
Toolsets), or the server refuses to start.
S100MutableTools.Create (namespace EncDotNet.S100.Mcp.MutableTools) builds
the tools that change a session. Each group of tools needs a capability from
the host, and you get only the tools whose capability you supply:
| Capability | Tools |
|---|---|
IMutableDatasetCatalog |
open_dataset, close_dataset, close_all_datasets |
IPresentationController |
set_palette, set_display_category, set_display_mode |
ITimeController |
set_time_step |
IViewportController |
set_viewport |
IImageRenderer |
render_to_image |
Pass each capability, except the catalog, through an
ICapabilityAccessor<T>, such as StaticCapabilityAccessor<T> (namespace
EncDotNet.S100.Hosting). If the accessor's Current is still null when a
tool is called, the tool returns a host_not_ready error, so a host can attach
a capability after the server starts. s100 mcp serve uses this to back the
tools with a headless renderer.
LibraryMcpAdapters and LibraryEditMcpAdapters (namespace
EncDotNet.S100.Mcp.Library) wrap the Library tools from
EncDotNet.S100.Mcp.Tools as MCP tools. SoundCharts serves them over its
Library.
TideMcpTools.Create (namespace EncDotNet.S100.Mcp.Tides) builds the
read-only tide and tidal current tools, list_tide_stations, predict_tide,
list_current_stations and predict_current, over an
ITideCatalogueSource, such as a TideCatalogueFileSource for the file
s100 tides update writes. SoundCharts and s100 mcp serve both serve them.
Tide tools and
Tidal current tools describe them.
Security
- The server listens on the loopback address by default, so other machines can't reach it.
S100McpServerhas no authentication. Any process on the machine can connect. Don't bind it to a routable address without an authenticating reverse proxy in front of it.s100 mcp serve --transport httpadds a bearer token and an origin check of its own; see MCP over HTTP.- SoundCharts starts it only when you turn it on. Its settings offer only a
loopback address; the
--mcp-bindcommand-line option can change it. - The built-in tools only read the catalog. Host tools you add can change host state. The Changes state column in MCP tools shows which ones do.
Errors
A tool that fails returns a tool result with isError set to true and a JSON
payload:
{
"code": "dataset_not_found",
"message": "Dataset 'foo' is not present in the catalog.",
"details": {}
}
code is the Code of the ToolError the tool returned, and details holds
that error's fields. An unexpected exception returns the code
internal_error. For the list of codes, see
Errors.
Coverage sample payloads
A coverage sample's value is one of several shapes. The JSON includes a
$kind property that names the shape: depth, water_level,
water_level_station, surface_current or surface_current_station.
Dependencies
ModelContextProtocolandModelContextProtocol.AspNetCore, version 1.4.0- ASP.NET Core, through the
Microsoft.AspNetCore.Appframework reference
Tests
tests/EncDotNet.S100.Mcp.Tests
runs the server end to end with the official MCP client. It covers the server
lifecycle, tool round trips, additional and mutating tools, error mapping, JSON
serialization, port conflicts and connection counts.