# alphaOS MCP Manager

The dedicated repository for the MCP Management plugin and chat picker in alphaOS.

Connect MCP servers once. Give your alphaOS agents read and write tools from one place.

This plugin adds a Connections dashboard, tool explorer, execution console,
an MCP picker next to the AI and Context pickers in chat, activity receipts,
CLI, and three provider-independent gateway tools:
`connectors_list`, `connectors_search`, and `connector_call`.

## Install

Requires alphaOS / bb 0.42 or later, Plugin SDK 0.4.47 or later, Node 22 and npm.

```sh
tar -xzf bb-plugin-mcp-management-0.2.2.tgz
cd package
npm install --omit=optional
bb plugin build
bb plugin install . --yes
```

Open **MCP Management** in the sidebar. Add an HTTP MCP server or import user-level
definitions from Claude and Codex. Select the project that should have access.
Test the connection, inspect the tools, and click **Enable tools**. Read & write
is the default access mode; tool schemas must be approved before execution.
New agent sessions receive the three gateway tools and discovery instructions.

## Choose MCPs in chat

The picker opens as a compact, searchable connection list. Click **MAX** to
expand into **Connections → Tools → Access**, then inspect a tool and choose
whether it follows connection access, asks first, or is blocked in this chat.
These choices cannot expand the permissions granted in connection settings.

Click **MCPs** next to the AI and Context pickers. Search connections and turn
each one on or off for that conversation. MAX also offers All ready on / All off. Turning a
connection off blocks its next gateway call without restarting the model.
Selections persist across reloads and do not change other conversations.
Open **MCP Management → Defaults** to choose which connections start on in new
conversations. **Notion is on by default; all other connections start off**, and
newly imported connections are never enabled automatically. The new-conversation
picker also edits these app-wide defaults. **Use defaults** resets a chat to the
current selection; **Edit defaults** opens the Defaults tab. Explicit selections
in other existing chats are preserved. In compact layouts, the picker appears
above the composer.
The picker narrows the hub's access; it does not disable a provider's separately
configured native MCP tools. Remove duplicate native connections separately
if you want all connector access to go through the hub's controls.

## Remove a connection

Select a connection in the dashboard and click **Remove connection**. Confirm to
remove its saved credentials, tool rules and picker/default selections. Activity
receipts stay available. Removal does not delete service data or the original
Claude/Codex configuration. Use **Disable connection** to pause access while
keeping the setup. A removed connection requires setup and tool approval again.

## Configuration

HTTP example (enter your credential directly in the dashboard):

```json
{"url":"https://your-mcp-server.example/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}
```

Local process example:

```json
{"command":"npx","args":["-y","your-mcp-server"],"env":{"YOUR_API_KEY":"YOUR_VALUE"}}
```

The URL and command examples are placeholders. Add only servers you trust:
local servers are executable programs running as your OS user.
HTTP uses Streamable HTTP, with a legacy SSE fallback for unsupported endpoints.
OAuth uses the MCP SDK's authorization flow with PKCE, stored refresh tokens and
a loopback callback. Click **Connect with OAuth**, authorize in your browser,
then test and enable tools. Some providers require a registered client and are
not compatible with automatic registration. No vendor-wide OAuth compatibility
claim is made.

## Write access and permissions

Connections can use Read & write, Confirm each call, Reviewed reads only or
Disabled mode. Project and provider restrictions are enforced on every call,
including calls from sessions opened before a permission change. Exact tool
names can be denied or individually require confirmation. The current schema
must be reviewed again if a tool changes upstream. Read-only mode uses an
operator-maintained list, never a server annotation as authorization.

The execution console supports real writes. A successful upstream response is
shown with a call receipt. Verify the destination when appropriate. Failed or
timed-out writes are never retried automatically because the destination may
already have processed them. Calls are serialized per connection.

## CLI

```sh
bb mcp-management import --dry-run
bb mcp-management import --project YOUR_PROJECT_ID
bb mcp-management test CONNECTION_ID
bb mcp-management enable-tools CONNECTION_ID
bb mcp-management list --json
bb mcp-management activity
bb mcp-management call CONNECTION_ID TOOL_NAME --args-file ./arguments.json --project YOUR_PROJECT_ID
bb mcp-management disable CONNECTION_ID
```

Imports preserve existing account configurations. User-level entries with the
same complete definition are deduplicated; different accounts stay separate.
Explicitly disabled source definitions are skipped.
Project-scoped definitions and Hermes profiles are not imported automatically.

## Hermes and external clients

In alphaOS threads, provider sessions that support the host's plugin tool bridge
receive the gateway tools. Independent Hermes gateways can connect to the
plugin's HTTP MCP endpoint through a separately configured private tunnel.
Create an external client in the Clients tab or with:

```sh
bb mcp-management client-create hermes --project YOUR_PROJECT_ID --output ./hermes-mcp.json
```

Each credential has a server-bound project and is individually revocable.
Set the returned URL and Bearer header in your client's MCP configuration.
The default URL is loopback: remote reachability and tunnel setup are separate.
External clients cannot approve unattended operations requiring confirmation.
Hermes Telegram configuration is not changed by installation. A local hub
depends on its host being available.

## Data and compatibility

Connection metadata, policy, tool schemas and the latest 1,000 call receipts
are in the plugin's SQLite database. Credentials use bb's secret setting
storage, not the registry, activity records or frontend read APIs. This is
owner-permission local secret storage, not an OS sandbox separating processes
running as the same user. Imports never expose original argument or header
values in previews. Subprocesses inherit a minimal environment plus their own
configured variables.

The hub proxies MCP tools. MCP resources, prompts, subscriptions, sampling,
elicitation and app-specific embedded UIs are not forwarded. Text and bounded
images are returned natively. Other content and structured data are serialized
as bounded text. Large results are truncated; paginate or narrow the upstream
query. Requests have bounded timeouts and execution cancellation.

## Development

```sh
npm install
npm run typecheck
npm test
bb plugin build
```

Landing page: https://briandecoded.com/mcp-management/
MIT licensed. Built by Brian Decoded.