Hosted connections

Creating a connection#

A hosted MCP connection is created once, stored by Coresource, and referenced from agent definitions by an opaque id. The credential is encrypted, injected only at Coresource's outbound relay, and never appears in an agent definition, a run, an event, or runtime configuration.

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

const coresource = new CoreSource();

const researchMcp = await coresource.mcp.connect({
  name: 'Research',
  url: 'https://mcp.example.com/rpc',
  auth: { type: 'bearer', token: process.env.RESEARCH_MCP_TOKEN ?? '' }
});

const researcher = createAgent({
  type: 'saga',
  systemPrompt: 'Prefer primary sources.',
  mcpServers: [{ connectionId: researchMcp.id, alias: 'research' }],
  outputs: ['research.md']
});

await researcher.close();

alias is the model-visible namespace: tools arrive as research/search and so on. Without one you get a positional name (mcp_1, mcp_2) which works but makes prompts and traces much harder to read.

trustedObservations is a security assertion made by your application, not a copy of the MCP server's readOnlyHint. List a tool only when the credential and remote resource boundary make it genuinely read-only; the runtime may use that certification when deciding whether a call is an observation or an external effect.

Authentication types#

Connections created with an API key are organization-scoped by default. Connections created from an authenticated user session are private to that user by default; an organization owner can explicitly select organization scope.

Managing connections#

import { CoreSource } from '@coresourceai/sdk';

const coresource = new CoreSource();

const page = await coresource.mcp.connections.list();
for (const connection of page.data) {
  console.log(connection.id, connection.name, connection.status);
}

// Rotate a static credential in place. Agents referencing it keep working.
await coresource.mcp.connections.rotateCredential('mcpconn_0123456789abcdef', {
  type: 'bearer',
  token: process.env.NEW_TOKEN ?? ''
});

// Restart an OAuth flow, e.g. after a revoked grant.
const reauthorized = await coresource.mcp.connections.authorize('mcpconn_fedcba9876543210');
console.log(reauthorized.authorizationUrl);

rotateCredential accepts only static credential types: bearer, api_key, and headers. OAuth connections are re-established with authorize instead, which is why the type system rejects passing an oauth credential here.

A connection exposes its state without exposing its secret: