Local MCP servers

Registering a server#

To run the MCP client yourself (for a server on your internal network, or one that needs local credentials), register it on the agent instead. Calls execute through your SDK process, exactly like a custom tool. The SDK does not include a default stdio or HTTP MCP client: provide a clientFactory that adapts your MCP client library to the SDK interface.

TypeScript

import { createAgent, type SdkMcpServer } from '@coresourceai/sdk';

const agent = createAgent({ type: 'agent' });

const local: SdkMcpServer = {
  name: 'internal',
  namespace: 'internal',
  transport: {
    kind: 'stdio',
    command: 'node',
    args: ['./mcp-servers/internal.js']
  },
  clientFactory: (transport) => createYourMcpClient(transport)
};

agent.registerMcpServer(local);

await agent.close();

declare function createYourMcpClient(
  transport: SdkMcpServer['transport']
): ReturnType<NonNullable<SdkMcpServer['clientFactory']>>;

transport is the configuration passed to your factory. It is either a stdio process or an http endpoint:

TypeScript

import type { SdkMcpServer } from '@coresourceai/sdk';

const overHttp: SdkMcpServer = {
  name: 'internal-http',
  transport: {
    kind: 'http',
    url: 'https://mcp.internal.example.com/rpc',
    headers: { authorization: `Bearer ${process.env.INTERNAL_TOKEN ?? ''}` }
  },
  clientFactory: (transport) => createYourMcpClient(transport)
};

declare function createYourMcpClient(
  transport: SdkMcpServer['transport']
): ReturnType<NonNullable<SdkMcpServer['clientFactory']>>;

`SdkMcpServer` field	Type	Notes
`name`	`string`	Required
`transport`	stdio or http config	Required
`namespace`	`string`	Model-visible prefix. Defaults to `name`
`displayName`	`string`	Human-readable label
`tools`	`readonly (string \| McpDiscoveredTool)[]`	Explicit tool names or descriptors to expose; otherwise the factory's discovery result is used
`clientFactory`	function	Creates the MCP client used for discovery and calls; required for tools to be executable
`policy`, `metadata`, `hooks`		Advanced

Like registerRuntimeTools(), this must happen before the first run starts.

Choosing between the two: hosted connections keep credentials out of your process and survive it exiting, which makes them right for third-party SaaS. Local registration is right when the server can only be reached from inside your network.