Developers

MCP

MCP Servers

The Model Context Protocol (MCP) is a standard for connecting AI agents to external tools and data sources. Nebo includes a built-in MCP bridge that manages server lifecycles, encrypts all communication, and makes MCP tools available to agents and activities.

Architecture

Nebo Agent
  |
  +-- MCP Bridge (AES-256-GCM encrypted)
        |
        +-- MCP Server: postgres    (separate process)
        +-- MCP Server: github      (separate process)
        +-- MCP Server: slack       (separate process)

Each MCP server runs as a separate process. The bridge manages process lifecycle, health checks, and encrypted communication. A server crash does not affect Nebo or other servers.

Configuration

MCP servers are configured via Nebo's settings UI or the configuration file.

Configuration File Format

mcp:
  servers:
    - name: my-database
      command: npx @modelcontextprotocol/server-postgres
      args:
        - postgresql://localhost/mydb
    - name: github
      command: npx @modelcontextprotocol/server-github
      env:
        GITHUB_TOKEN: ${GITHUB_TOKEN}
    - name: slack-notifier
      command: npx @modelcontextprotocol/server-slack
      env:
        SLACK_BOT_TOKEN: ${SLACK_BOT_TOKEN}
        SLACK_TEAM_ID: ${SLACK_TEAM_ID}

Server Configuration Fields

Field Type Required Description
name string Yes Unique identifier. Referenced in agent activities via mcps[].
command string Yes Executable to launch the server.
args string[] No Command-line arguments passed to the server.
env object No Environment variables. Supports ${VAR} syntax for referencing system env vars.

Using MCP in Agents

Agent activities reference MCP servers by name via the mcps field. When the activity executes, the listed servers are made available and the agent can call their advertised tools.

{
  "id": "query-database",
  "intent": "Look up the latest sales figures from the database",
  "skills": [],
  "mcps": ["my-database"],
  "cmds": [],
  "model": "claude-sonnet",
  "steps": [],
  "token_budget": 2048,
  "on_error": "stop"
}

Multiple MCP servers can be available to a single activity:

{
  "id": "cross-reference",
  "intent": "Cross-reference GitHub issues with database records and post a summary to Slack",
  "skills": ["report-writer"],
  "mcps": ["github", "my-database", "slack-notifier"],
  "cmds": [],
  "model": "claude-sonnet",
  "steps": [],
  "token_budget": 4096,
  "on_error": "stop"
}

Security Model

Encryption

All communication between Nebo and MCP servers is encrypted with AES-256-GCM. This applies to both the JSON-RPC messages and any tool call payloads, regardless of whether the server runs locally or remotely.

Process Isolation

Each MCP server runs in its own process. This provides:

  • Fault isolation: A crashing server does not affect Nebo or other servers.
  • Resource isolation: Servers have independent memory and CPU usage.
  • Lifecycle management: Nebo starts, stops, and restarts servers independently.

User Consent

  • Users must explicitly approve each MCP server connection before it becomes active.
  • The server's advertised tools are shown to the user for review.
  • Users can revoke access to individual servers at any time.
  • Tool access is governed by Nebo's policy engine -- the same system that manages skill capabilities.

Environment Variables

Sensitive values (API tokens, database credentials) should be provided via environment variables, not hardcoded in the configuration file. Use the ${VAR} syntax to reference system environment variables:

env:
  GITHUB_TOKEN: ${GITHUB_TOKEN}

For agent activities that need secrets, use the skill secrets system (metadata.secrets[] in SKILL.md) rather than MCP env vars when possible. Skill secrets are encrypted with AES-256-GCM at rest and scoped to the declaring skill.

Communication Protocol

MCP uses JSON-RPC over stdio (standard input/output). The protocol flow:

  1. Nebo launches the server process via the configured command and args.
  2. The server advertises its available tools (name, description, input schema) over stdio.
  3. Nebo registers the tools and makes them available to activities that reference the server.
  4. When an activity invokes a tool, Nebo sends a JSON-RPC request to the server's stdin.
  5. The server processes the request and writes the response to stdout.
  6. Nebo decrypts and returns the result to the activity.

Building an MCP Server

MCP servers can be built in any language. The protocol is JSON-RPC over stdio. Popular SDKs:

Language Package
TypeScript @modelcontextprotocol/sdk
Python mcp
Rust mcp-rs
Go mcp-go

A minimal server exposes one or more tools, each with a name, description, and JSON Schema input definition. Nebo handles discovery, encryption, and lifecycle management.

Minimal TypeScript Example

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-tool",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "lookup",
    description: "Look up a value by key",
    inputSchema: {
      type: "object",
      properties: {
        key: { type: "string", description: "The key to look up" }
      },
      required: ["key"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;
  if (name === "lookup") {
    const result = await doLookup(args.key);
    return { content: [{ type: "text", text: result }] };
  }
  throw new Error(`Unknown tool: ${name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

Next Steps

Agent Reference Design Principles