Lesson 17: Hosting and Consuming MCP Servers

MCP in both directions - consume remote servers from Agent.bx, host your own under mcp/.

Hosting and Consuming MCP Servers

Model Context Protocol (MCP) works in two directions in a BxAgents project, and nothing links them - an agent consuming remote servers need not host one, and a hosted server is only reachable if a gateways/ entry exposes it (see Lesson 13).

flowchart LR
    subgraph consume["CONSUMING - declared on Agent.bx"]
        direction LR
        AG["your agent"] -->|"calls out at runtime"| RM["a remote MCP server"]
    end
    subgraph host["HOSTING - one file per server under mcp/"]
        direction LR
        TL["tools/"] -->|"a named SUBSET"| MS["mcpServer('localServer')"]
        MS --> GW["gateways/ entry, exposes: mcp"]
    end
    style consume fill:#e7f1ff,stroke:#004085
    style host fill:#eaf6ec,stroke:#155724

Consuming a remote server

Declared directly on Agent.bx via mcpServers - not a file under mcp/:

function configure() {
	return {
		mcpServers : [
			"https://example.com/mcp",
			{ url : "https://other.com/mcp", name : "other" }
		]
	};
}

No network connection is ever attempted at build time - reachability is a runtime concern, so an unreachable server at build time is not a build error. Subagents can declare their own mcpServers independently.

Hosting a local server

Each mcp/*.bx file is a local MCP server your project hosts, exposing a named subset of your tools/ (from Lesson 9) as MCP tools:

// mcp/localServer.bx
class {
	function configure() {
		return {
			description : "Internal tools MCP server",
			version     : "1.0.0",
			cors        : "*",             // optional
			tools       : [ "sayHello" ]   // names of tools already under tools/
		};
	}
}

The entry's discovered name is its filename (localServer.bx -> localServer), not any name inside configure(). At build time the file is copied verbatim, and a registration statement is emitted at startup.

Exposing it over HTTP

A local server isn't reachable on its own - pair it with the gateways/ exposure entry you saw in Lesson 13:

// gateways/expose-mcp.bx
class {
	function configure() {
		return {
			exposes : "mcp",
			path    : "/mcp/tools",
			target  : "localServer"
		};
	}
}

Try it

Host the GetTime tool you wrote in Lesson 9 as its own MCP server, expose it at /mcp/tools, build, and serve - it's now reachable by any outside MCP client, independent of your agent's own chat interface.

Full reference: mcp/.

Next: Lesson 18 - Interceptors and Module Dependencies