SharedOS API / @aicoo/sharedos-mcp

@aicoo/sharedos-mcp

The SharedOS permission-filtered tool catalogue, served to external harnesses as a Model Context Protocol server.

npm install @aicoo/sharedos-mcp@next

Harness configuration declares a CONNECTION.
SharedOS declares the TOOLS.
SharedOS capabilities declare the AUTHORITY.
RuntimeHost is the only EXECUTION path.

This is the other half of the harness story. @aicoo/sharedos-adapters puts SharedOS in the model provider's seat and owns the turn loop; this package lets a vendor CLI keep its own loop and whatever model it is configured with, and connect to SharedOS as a tool server. Both converge on RuntimeHost.invokeTool, so neither adds a second permission path.

import { McpToolServer, openToolBridge } from "@aicoo/sharedos-mcp";
import { createStreamableHttpMcpServer } from "@aicoo/sharedos-mcp/node";

// Inside RuntimePlugin.run(request, host, signal):
const bridge = openToolBridge({
  executionId: request.executionId,
  context: { traceId: request.context.traceId, now: request.context.now },
  tools: request.tools, // already permission-filtered by the envelope
  host, // RuntimeHost: every call is re-authorized
});
const http = await createStreamableHttpMcpServer({
  server: new McpToolServer({ invoker: bridge }),
});
try {
  // ... point the harness at http.url ...
} finally {
  bridge.close();
  await http.close();
}

One name

ToolDefinition.name  =  SharedOS canonical tool ID  =  raw MCP Tool.name

There is no second identity in the published catalogue. A harness alias (mcp__sharedos__files_read) is presentation: it is recorded on the bridge for diagnosis, never on the ToolCall, so it cannot reach an authorization decision.

What crosses the boundary

PublishedToolDefinition carries name, description, inputSchema, outputSchema, MCP annotation hints, and catalogue provenance. It carries no requiredCapability, no resolveRequirement, no grants, no issuing authority, no namespace settings, no credentials, and no handler references.

The omission is load-bearing. Authorization is resource + action + context resolved from the arguments at call time, so two calls to one published tool routinely need different authority.

Refusals are results

A SharedOS denial comes back as an MCP tool error (isError: true), never as a transport error. A JSON-RPC error means the request could not be processed; a denial is a processed request whose answer is "no", and a harness needs to be able to report it and carry on. denied and failed stay distinguishable in the payload and in _meta["sharedos/status"].

Per turn, never global

The bridge is opened for one AccessContext, exposed for one turn, and torn down with it. A harness process that outlives its turn finds a shut door rather than a catalogue resolved for a turn that has ended.

Catalogue hashes

catalogHash = SHA-256(canonical JSON(tools sorted by canonical name))

Field participation is fixed by CATALOG_HASH_FIELDS, so two implementations cannot both claim to compute it and disagree. Two harnesses whose hashes match were served the same semantic tool set; two whose hashes differ cannot be compared until that is explained.

Full design: MCP toolshare and ADR 0014.

SharedOS is currently an 0.x prerelease.

Classes

McpToolServer

Defined in: mcp/src/server.ts:114

SharedOS's catalogue and authorization broker, spoken as MCP.

The server is transport-agnostic on purpose: it turns one JSON-RPC message into one JSON-RPC response, and knows nothing about stdio, HTTP, sessions, or processes. That is what lets the same translation be exercised deterministically in a unit test and then serve a live CLI without changing the code under test.

It holds no policy. Every tools/call is handed to the invoker, which puts it through RuntimeHost.invokeTool and the kernel; the server never decides that a call should be refused, and never decides that one should be allowed. Its one substantive job is translation, and the translation rule that matters is that a SharedOS refusal is a tool result, never a transport error -- see toCallToolResult.

Constructors

Constructor

new McpToolServer(options): McpToolServer

Defined in: mcp/src/server.ts:123

Parameters

Parameter	Type
`options`	`McpToolServerOptions`

Parameter	Type
`context`	{ `actor`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `authority`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `enabledToolNamespaces`: `string`[]; `namespaceId`: `string`; `now`: `string`; `owner`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `purpose`: `string`; `traceId`: `string`; }
`context.actor`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.authority`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.enabledToolNamespaces?`	`string`[]
`context.namespaceId?`	`string`
`context.now?`	`string`
`context.owner?`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.purpose?`	`string`
`context.traceId?`	`string`
`call?`	{ `arguments`: `JsonObject`; `id`: `string`; `requestedAt`: `string`; `tool`: `string`; `traceId`: `string`; }
`call.arguments?`	`JsonObject`
`call.id?`	`string`
`call.requestedAt?`	`string`
`call.tool?`	`string`
`call.traceId?`	`string`
`options?`	{ `signal?`: `AbortSignal`; }
`options.signal?`	`AbortSignal`

Parameter	Type
`call`	{ `arguments`: `JsonObject`; `id`: `string`; `requestedAt`: `string`; `tool`: `string`; `traceId`: `string`; }
`call.arguments`	`JsonObject`
`call.id?`	`string`
`call.requestedAt?`	`string`
`call.tool?`	`string`
`call.traceId?`	`string`
`options?`	{ `step?`: `number`; }
`options.step?`	`number`

Property	Modifier	Type	Defined in
<a id="property-now"></a> `now`	`readonly`	`string`	mcp/src/bridge.ts:33
<a id="property-traceid"></a> `traceId`	`readonly`	`string`	mcp/src/bridge.ts:32

Property	Modifier	Type	Description	Defined in
<a id="property-externaldirect"></a> `externalDirect?`	`readonly`	readonly `string`[]	MCP servers the harness was configured with independently.	mcp/src/policy.ts:24
<a id="property-harnesslocal"></a> `harnessLocal?`	`readonly`	readonly `string`[]	The harness's own tools, which SharedOS never sees.	mcp/src/policy.ts:22
<a id="property-managedmcp"></a> `managedMcp?`	`readonly`	readonly `string`[]	SharedOS MCP endpoints. Defaults to the one this package serves.	mcp/src/policy.ts:20
<a id="property-mode"></a> `mode?`	`readonly`	`"strict"` \| `"hybrid"`	-	mcp/src/policy.ts:18

Property	Modifier	Type	Defined in
<a id="property-contents"></a> `contents`	`readonly`	`string`	mcp/src/harness-config.ts:39
<a id="property-filename"></a> `filename`	`readonly`	`string`	mcp/src/harness-config.ts:38
<a id="property-harness"></a> `harness`	`readonly`	`string`	mcp/src/harness-config.ts:37

Property	Modifier	Type	Description	Defined in
<a id="property-name"></a> `name?`	`readonly`	`string`	The server name the harness will namespace its aliases under.	mcp/src/harness-config.ts:28
<a id="property-timeoutsec"></a> `timeoutSec?`	`readonly`	`number`	Per-call timeout in the emitted config. Set by nothing today; see `docs/open-items.md`.	mcp/src/harness-config.ts:30
<a id="property-token"></a> `token?`	`readonly`	`string`	Bearer token for a sandboxed or remote harness.	mcp/src/harness-config.ts:32
<a id="property-url"></a> `url`	`readonly`	`string`	The Streamable HTTP endpoint the turn-scoped bridge is serving.	mcp/src/harness-config.ts:26

Property	Modifier	Type	Defined in
<a id="property-code"></a> `code`	`readonly`	`number`	mcp/src/protocol.ts:62
<a id="property-data"></a> `data?`	`readonly`	`unknown`	mcp/src/protocol.ts:64
<a id="property-message"></a> `message`	`readonly`	`string`	mcp/src/protocol.ts:63

Property	Modifier	Type	Defined in
<a id="property-error"></a> `error`	`readonly`	`JsonRpcErrorBody`	mcp/src/protocol.ts:76
<a id="property-id"></a> `id`	`readonly`	`string` \| `number` \| `null`	mcp/src/protocol.ts:75
<a id="property-jsonrpc"></a> `jsonrpc`	`readonly`	`"2.0"`	mcp/src/protocol.ts:74

Property	Modifier	Type	Defined in
<a id="property-id-1"></a> `id`	`readonly`	`string` \| `number`	mcp/src/protocol.ts:69
<a id="property-jsonrpc-1"></a> `jsonrpc`	`readonly`	`"2.0"`	mcp/src/protocol.ts:68
<a id="property-result"></a> `result`	`readonly`	`unknown`	mcp/src/protocol.ts:70

Property	Modifier	Type	Description	Defined in
<a id="property-context"></a> `context`	`readonly`	`object`	The trusted context. Never built from anything the harness sent.	mcp/src/bridge.ts:170
`context.actor`	`public`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	-	contracts/dist/access.d.ts:144
`context.authority`	`public`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	-	contracts/dist/access.d.ts:157
`context.enabledToolNamespaces`	`public`	`string`[]	-	contracts/dist/access.d.ts:170
`context.namespaceId`	`public`	`string`	-	contracts/dist/access.d.ts:141
`context.now`	`public`	`string`	-	contracts/dist/access.d.ts:171
`context.owner`	`public`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	-	contracts/dist/access.d.ts:128
`context.purpose`	`public`	`string`	-	contracts/dist/access.d.ts:142
`context.traceId`	`public`	`string`	-	contracts/dist/access.d.ts:143
<a id="property-executionid"></a> `executionId`	`readonly`	`string`	-	mcp/src/bridge.ts:171
<a id="property-kernel"></a> `kernel`	`readonly`	`BridgeKernel`	-	mcp/src/bridge.ts:168

Parameter	Type
`invocation`	`McpToolInvocation`
`signal`	`AbortSignal`

Parameter	Type
`invocation`	`McpToolInvocation`
`signal`	`AbortSignal`

Property	Modifier	Type	Description	Defined in
<a id="property-createid"></a> `createId?`	`readonly`	() => `string`	Mints the SharedOS call id for one `tools/call`.	mcp/src/server.ts:69
<a id="property-instructions"></a> `instructions?`	`readonly`	`string`	Guidance handed to the client at initialize time.	mcp/src/server.ts:67
<a id="property-invoker"></a> `invoker`	`readonly`	`McpToolInvoker`	-	mcp/src/server.ts:64
<a id="property-serverinfo"></a> `serverInfo?`	`readonly`	`McpServerInfo`	-	mcp/src/server.ts:65
<a id="property-spans"></a> `spans?`	`readonly`	`SpanSink`	Where the cost of answering one frame is reported. This is the span that bounds enforcement over the toolshare path: it opens when a frame arrives here and closes when the response leaves, so the model's own thinking time is outside it by construction rather than by subtraction. What is also outside it, and cannot be brought in, is the vendor CLI's own tool router -- that code runs before a frame reaches this server and SharedOS never sees it.	mcp/src/server.ts:80

Property	Modifier	Type	Description	Defined in
<a id="property-context-1"></a> `context`	`readonly`	`BridgeTurnContext`	-	mcp/src/bridge.ts:45
<a id="property-executionid-1"></a> `executionId`	`readonly`	`string`	-	mcp/src/bridge.ts:44
<a id="property-host"></a> `host`	`readonly`	`BridgeToolInvoker`	-	mcp/src/bridge.ts:48
<a id="property-step"></a> `step?`	`readonly`	`number`	Position in the harness's own loop, when the transport can report one. Neither caller passes it today, so an MCP-mediated call declares no step and is bounded by `maxToolCalls` alone; see `docs/open-items.md`.	mcp/src/bridge.ts:54
<a id="property-tools"></a> `tools`	`readonly`	readonly `object`[]	The permission-filtered catalogue this turn resolved.	mcp/src/bridge.ts:47

Property	Modifier	Type	Defined in
<a id="property-name-1"></a> `name`	`readonly`	`string`	mcp/src/server.ts:59
<a id="property-version"></a> `version`	`readonly`	`string`	mcp/src/server.ts:60

Property	Modifier	Type	Description	Defined in
<a id="property-alias"></a> `alias?`	`readonly`	`string`	The name the harness actually sent, when it was not the canonical one.	mcp/src/server.ts:40
<a id="property-arguments"></a> `arguments`	`readonly`	`JsonObject`	-	mcp/src/server.ts:38
<a id="property-callid"></a> `callId`	`readonly`	`string`	-	mcp/src/server.ts:35
<a id="property-tool"></a> `tool`	`readonly`	`string`	The canonical SharedOS tool name, or the raw one when it matched nothing.	mcp/src/server.ts:37

Property	Modifier	Type	Defined in
<a id="property-alias-1"></a> `alias`	`readonly`	`string`	mcp/src/bridge.ts:38
<a id="property-at"></a> `at`	`readonly`	`string`	mcp/src/bridge.ts:40
<a id="property-tool-1"></a> `tool`	`readonly`	`string`	mcp/src/bridge.ts:39

Property	Modifier	Type	Description	Defined in
<a id="property-expect"></a> `expect?`	`readonly`	`Partial`<{ `actor`: `string`; `catalogHash`: `string`; `executionId`: `string`; `expiresAt`: `string`; `namespaceId`: `string`; }>	Claims the session already knows, each of which must match exactly.	mcp/src/token.ts:80
<a id="property-now-1"></a> `now`	`readonly`	`string`	The instant to judge expiry against. RFC 3339.	mcp/src/token.ts:78

Parameter	Type
`policy`	{ `externalDirect`: `string`[]; `harnessLocal`: `string`[]; `managedMcp`: `string`[]; `mode`: `"strict"` \| `"hybrid"`; }
`policy.externalDirect`	`string`[]
`policy.harnessLocal`	`string`[]
`policy.managedMcp`	`string`[]
`policy.mode`	`"strict"` \| `"hybrid"`
`publishedNames`	readonly `string`[]
`tool`	`string`

Parameter	Type
`harness`	`"codex"` \| `"claude-code"` \| `"deepseek"` \| `"pi"`
`connection`	`HarnessMcpConnection`

Parameter	Type
`id`	`string` \| `number` \| `null`
`code`	`number`
`message`	`string`
`data?`	`unknown`

Parameter	Type	Description
`claims`	{ `actor`: `string`; `catalogHash`: `string`; `executionId`: `string`; `expiresAt`: `string`; `namespaceId`: `string`; }	-
`claims.actor`	`string`	The acting principal as canonicalActor renders it: `<kind>:<id>`, for example `agent:a-1`. Compared by equality, never parsed back.
`claims.catalogHash`	`string`	-
`claims.executionId`	`string`	-
`claims.expiresAt`	`string`	RFC 3339. A token with no expiry is not issued.
`claims.namespaceId`	`string`	-
`secret`	`string`	-

Parameter	Type
`result`	{ `callId`: `string`; `completedAt`: `string`; `metadata?`: `JsonObject`; `output`: `JsonValue`; `status`: `"succeeded"`; `tool`: `string`; } \| { `callId`: `string`; `completedAt`: `string`; `error`: { `code`: `string`; `details?`: `JsonObject`; `message`: `string`; `retryable?`: `boolean`; }; `metadata?`: `JsonObject`; `status`: `"denied"`; `tool`: `string`; } \| { `callId`: `string`; `completedAt`: `string`; `error`: { `code`: `string`; `details?`: `JsonObject`; `message`: `string`; `retryable?`: `boolean`; }; `metadata?`: `JsonObject`; `status`: `"failed"`; `tool`: `string`; }
`published?`	{ `annotations?`: { `destructiveHint?`: `boolean`; `idempotentHint?`: `boolean`; `openWorldHint?`: `boolean`; `readOnlyHint?`: `boolean`; }; `description`: `string`; `inputSchema`: `JsonObject`; `metadata?`: { `namespace?`: `string`; `source?`: `string`; }; `name`: `string`; `outputSchema?`: `JsonObject`; }
`published.annotations?`	{ `destructiveHint?`: `boolean`; `idempotentHint?`: `boolean`; `openWorldHint?`: `boolean`; `readOnlyHint?`: `boolean`; }
`published.annotations.destructiveHint?`	`boolean`
`published.annotations.idempotentHint?`	`boolean`
`published.annotations.openWorldHint?`	`boolean`
`published.annotations.readOnlyHint?`	`boolean`
`published.description?`	`string`
`published.inputSchema?`	`JsonObject`
`published.metadata?`	{ `namespace?`: `string`; `source?`: `string`; }
`published.metadata.namespace?`	`string`
`published.metadata.source?`	`string`
`published.name?`	`string`
`published.outputSchema?`	`JsonObject`

Parameter	Type
`tool`	{ `annotations?`: { `destructiveHint?`: `boolean`; `idempotentHint?`: `boolean`; `openWorldHint?`: `boolean`; `readOnlyHint?`: `boolean`; }; `description`: `string`; `inputSchema`: `JsonObject`; `metadata?`: { `namespace?`: `string`; `source?`: `string`; }; `name`: `string`; `outputSchema?`: `JsonObject`; }
`tool.annotations?`	{ `destructiveHint?`: `boolean`; `idempotentHint?`: `boolean`; `openWorldHint?`: `boolean`; `readOnlyHint?`: `boolean`; }
`tool.annotations.destructiveHint?`	`boolean`
`tool.annotations.idempotentHint?`	`boolean`
`tool.annotations.openWorldHint?`	`boolean`
`tool.annotations.readOnlyHint?`	`boolean`
`tool.description`	`string`
`tool.inputSchema`	`JsonObject`
`tool.metadata?`	{ `namespace?`: `string`; `source?`: `string`; }
`tool.metadata.namespace?`	`string`
`tool.metadata.source?`	`string`
`tool.name`	`string`
`tool.outputSchema?`	`JsonObject`

Parameter	Type
`token`	`string`
`secret`	`string`
`options`	`VerifyExecutionTokenOptions`