MCP (Model Context Protocol) Services — development
This section is for developers working on the MCP (Model Context Protocol) Services itself — building from source, running it against a local OctoMesh stack, and understanding the configuration surface. For end-user documentation (registering the hosted endpoints with Claude Code, available tools, troubleshooting), see MCP Services in the Tech Guide.
Repository
The implementation lives in the octo-mcp-service repository:
octo-mcp-service/
├── src/McpServices/ # ASP.NET host + tool classes
├── tests/McpServices.Tests/ # 400+ unit tests
├── docs/ # Internal concepts (risk classification sweep, etc.)
├── Dockerfile
├── azure-pipelines.yml
├── Octo.McpServices.sln
├── README.md # User-facing README — duplicates parts of this doc set
└── CLAUDE.md # Coding conventions for AI assistants editing the repo
The authoritative source for code-level conventions is CLAUDE.md in the repository — it covers the mandatory tool-class pattern, response envelope, optimistic locking, file-transfer architecture, aggregation mapper, and test-suite layout.
Three tool families
| Family | Path through the stack | Used by |
|---|---|---|
| Platform-admin tools (~140) | HTTP to backend services via OctoServiceClientFactory + *ClientContext helpers — same code path the CLI uses | octo-cli parity tools (tenant, identity, blueprint, communication, time-series, reporting, file I/O) |
| Generic CK CRUD + schema tools (~13) | Direct to ITenantRepository (MongoDB) — no HTTP overhead | query_entities, create_entity, get_type_schema, etc. |
| Aggregation + stream-data query tools (~10) | Direct to the engine via ITenantRepository / ITenantContext.GetStreamDataRepository(), with the lowercase AggregationFunctionDto enum and AggregationMapper | query_entities_aggregation, query_stream_data_downsampling, persisted-query replay |
These are kept separate on purpose — see CLAUDE.md § Background for the reasoning. Don't try to merge them.
What's in this section
- Local development — Building, running against
Start-Octo, registering a local server with Claude Code, port layout. - Configuration —
appsettings.json, environment variables, backend service URLs, file-transfer limits, caching, health probes.
Build & test (cheat sheet)
# Build the MCP server
dotnet build src/McpServices/McpServices.csproj -c DebugL
# Build the entire solution (server + tests + resources)
dotnet build Octo.McpServices.sln -c DebugL
# Run all tests (~400 tests, ~250 ms)
dotnet test Octo.McpServices.sln -c DebugL
# Filter tests by class
dotnet test --filter "FullyQualifiedName~TenantManagementToolsTests"
# Run dev server (binds to 5016 HTTP / 5017 HTTPS)
cd src/McpServices && dotnet run --environment Development
Build configurations: Debug, Release, DebugL (local dev with OctoVersion=999.0.0, uses local NuGet packages from ../nuget/).
TreatWarningsAsErrors is enabled. CS1591 (missing XML doc) breaks the build for any public member of McpServices — every public type, property, and method on a new tool class needs an XML doc summary.