Skip to main content
MCP (Model Context Protocol) is the open standard the RubixKube agent mesh uses to reach external tools. A Custom MCP Server lets you expose internal tools, data platforms, or bespoke runbooks to the SRI Agent with typed arguments and scoped authorisation. Use this path when you want richer-than-REST behaviour: bidirectional tool calls, streaming responses, shared context, or tools that orchestrate multiple underlying APIs behind one call.

​
When to choose MCP over REST

MCP is best for

Tools that need structured tool schemas, rich return types, streaming outputs, or coordinated multi-call workflows.

REST is best for

Single endpoints that already have OpenAPI specs and simple request-response semantics. See Custom REST Integrations.

​
What an MCP server exposes

An MCP server advertises a set of tools. Each tool has:
  • A name (unique handle).
  • A description (one sentence, used for intent matching).
  • A JSON schema for its arguments (types, enums, ranges).
  • A handler that runs the tool and returns structured output.
RubixKube reads the advertised tool list and makes each tool callable by the SRI Agent, scoped by the skill’s allowed_tools list.

​
Minimal server (TypeScript SDK)

import { Server } from "@modelcontextprotocol/sdk/server";
import { z } from "zod";

const server = new Server({ name: "internal-incident-runbook", version: "1.0.0" });

server.tool(
  "fetch_customer_impact",
  {
    description: "Look up which customers are currently affected by a service outage.",
    inputSchema: z.object({
      serviceName: z.string(),
      sinceMinutes: z.number().int().min(1).max(1440)
    })
  },
  async ({ serviceName, sinceMinutes }) => {
    // Your internal implementation
    return {
      affectedCustomerCount: 142,
      topRegions: ["ap-south-1", "eu-west-1"]
    };
  }
);

server.start();

​
Hosting modes

Push a container image to a registry we can pull from, plus a manifest that declares resources. RubixKube runs the server in an isolated sandbox inside RubixKube Cloud. Simplest path for most teams.

​
Register the server

1

Declare the server in the console

Open Integrations → Custom MCP and choose RubixKube-managed or Self-hosted. Provide the image reference or tunnel endpoint.
2

Validate the tool schemas

The console lists every tool the server advertises. Click each to inspect the JSON schema and run a test call.
3

Set auth

Pick the auth type that matches your server (API key, OAuth, mTLS). Store credentials in the workspace secret vault. See OAuth and Auth Types.
4

Scope to skills

Add the server’s tools to the allowed_tools list of the skills that need them. Do not enable tools globally unless they are strictly read-only.

​
Design guidelines

Narrow, typed arguments

Enums and ranges beat free-form strings. The planner’s accuracy rises sharply with good schemas.

Idempotent reads, explicit writes

Read tools can run freely. Write tools should require approval via the RubixKube action flow.

Fast responses

Target sub-second p95 for read tools. Long-running operations should return a task handle and let Chat poll.

Descriptive errors

Return structured error payloads with reason codes. They feed back into planning and future recommendations.

​
Safety and Guardian

A custom MCP server is not a bypass of Guardian. Mutating tools still pass through the approval flow before they can run. Reads are permitted freely but can still be scoped by environment, team, or time window.

​
Troubleshooting

RubixKube discovers tools via the MCP tools/list call on connect. If nothing appears, check the server log for errors during the handshake and that the SDK version is at least 1.0.
The argument the SRI Agent sent did not match your schema. Tighten the description and examples so intent mapping aligns with what the tool accepts.
The outbound tunnel dropped. Check the tunnel health in Integrations → Custom MCP → Tunnel. Most commonly this is a restart of the self-hosted host without auto-reconnect.

Custom REST Integrations

When OpenAPI is enough.

OAuth and Auth Types

Reference for every supported authentication method.

How to add custom integrations

Walkthrough of the full custom integration flow.