Bring Your Own MCP Tools — Overview

What Is an External MCP Server?

An external MCP server is any HTTP service that exposes two endpoints:

GET /tools — returns the list of available tools with their JSON Schema definitions
POST /tool/{name}/call — executes a specific tool and returns the result as JSON

Octopus discovers the tools at agent startup, presents them to the LLM as part of its capability set, and calls POST /tool/{name}/call whenever the agent decides to use one. From the agent's perspective, an external MCP tool is indistinguishable from a built-in plugin tool.

When to Use External MCP Servers

Legacy System Integration

Wrap an existing REST or SOAP service behind the MCP contract without modifying the Octopus host or writing an IOctopusPlugin.

Polyglot Tool Servers

Write the tool server in Python, Go, or Node.js if that language has better library support for the integration target (e.g. a Python ML model).

Independently Deployed Services

Deploy and scale your tool server independently from the Octopus host — update tools without restarting the agent runtime.

Shared Tool Infrastructure

Multiple Octopus deployments (dev, staging, prod) can share a single external MCP server for common enterprise tools.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Octopus Host                             │
│                                                                 │
│   Agent Engine ──(tool call)──► MCPToolProxy                   │
│                                      │                          │
│                              (HTTP POST /tool/{name}/call)      │
└──────────────────────────────────────┼──────────────────────────┘
                                       │
                          Authorization: Bearer {token}
                                       │
                         ┌─────────────▼──────────────┐
                         │   External MCP Tool Server  │
                         │                             │
                         │   GET /tools                │
                         │   POST /tool/{name}/call    │
                         │                             │
                         │   Your business logic here  │
                         └─────────────────────────────┘

MCP Contract at a Glance

Endpoint	Method	Request	Response
`/tools`	GET	—	JSON array of tool descriptors
`/tool/{name}/call`	POST	JSON object matching `inputSchema`	JSON result object
`/health`	GET	—	`{"status":"ok"}` (recommended)

What This Guide Covers

Page	Topic
MCP Server Protocol	Full wire format: `GET /tools` and `POST /tool/.../call` JSON shapes
Defining Tool Schemas	JSON Schema best practices for `inputSchema` and `outputSchema`
C# MinimalAPI Server	Complete C# MinimalAPI implementation with DI, tool registry, and handler routing
Agent Registration	How to register an external MCP server in an agent's configuration
Authentication	Bearer token flow via `ICredentialResolver`, mTLS option
Testing MCP Tools	Unit testing handlers, integration testing the wire contract, curl examples
Packaging and Publishing	Docker packaging, health probes, versioning, and community registry submission

Next: MCP Server Protocol →