> For the complete documentation index, see [llms.txt](https://thecontentforge.gitbook.io/thecontentforge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/local-agent-bridge.md).

# Local Agent Bridge

The Local Agent Bridge is a second, local way to use an Investor Intel agent token. It is a small MCP server that runs on your own computer and talks to your agent client (Claude Desktop, Claude Code, Goose or any other stdio MCP client) over stdio. It opens no network port. It uses the same token, the same scopes and the same approvals as the [Hosted MCP Server](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/hosted-mcp.md).

Use it for the scopes the hosted server has no tool for:

* **Portfolio** (`read:portfolio`): your portfolios and holdings.
* **Theses** (`read:thesis`): your written theses.
* **Charts** (`read:charts`): your saved chart views.
* The two approval writes **Annotate charts** (`write:charts`) and **Add thesis evidence** (`write:thesis`).

The bridge also reads alerts, watchlists and evidence, and proposes alerts. The market and tokenized real-world-asset tools, watchlist adds, research notes and the Daily Brief, Explain This and saved research read-backs are on the hosted server only. One token can be used in both places at once.

The bridge is not published as a package. To get a copy, email <support@thecontentforge.io>.

## Install

You need Node 22 or newer. In the bridge's folder:

```bash
cd local-agent-bridge
npm install
```

## Store your token on this computer

Create a token on the **Agents** page (`/intel/agents`), see [Agents and Agent Access](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/agent-access.md), then store it:

```bash
npm run agent-token -- set
```

Paste the token when asked; it is not shown on screen. It goes into the operating system's protected store (Keychain on macOS, DPAPI on Windows, an owner-only file on Linux), never into the client's config file. Run this as the same OS user your agent client runs as: on Windows the DPAPI store only opens for that user. `npm run agent-token -- status` shows what is stored.

The Investor Intel tools need only the token. If you have not also signed in (see [Manage tokens from the command line](#manage-tokens-from-the-command-line)), the bridge prints a "No stored session" warning when it starts; the Investor Intel tools still work.

Never paste a token into a client config file, a chat with the agent, a shared document or a repository. No config key accepts one.

## Add it to your client

Every client needs the same two things: the command `node` and one argument, the **absolute** path to `bin/forge-mcp.js` in the bridge's folder. No port, no URL and no secret go in the config.

**Claude Desktop.** In **Settings > Developer > Edit Config**, merge a `contentforge` entry into `mcpServers` in `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`), keeping any servers already there:

```json
{
  "mcpServers": {
    "contentforge": {
      "command": "node",
      "args": ["/absolute/path/to/local-agent-bridge/bin/forge-mcp.js"]
    }
  }
}
```

On Windows use forward slashes in the path, for example `C:/Users/you/local-agent-bridge/bin/forge-mcp.js`. If Claude Desktop cannot find `node`, put the absolute path from `which node` (macOS) or `where node` (Windows) in its place. Fully quit and reopen Claude Desktop after editing.

**Claude Code.** Register it once for your user:

```bash
claude mcp add --transport stdio --scope user contentforge -- node /absolute/path/to/local-agent-bridge/bin/forge-mcp.js
```

Check it with `claude mcp list`, or `/mcp` inside a session.

**Goose.** Run `goose configure`, choose **Add Extension**, then **Command-line Extension**:

| Field   | Value                                                        |
| ------- | ------------------------------------------------------------ |
| Name    | `contentforge`                                               |
| Command | `node /absolute/path/to/local-agent-bridge/bin/forge-mcp.js` |
| Timeout | `300`                                                        |

Or run `node scripts/configure-goose.mjs` in the bridge's folder: it fills in the absolute path and merges the entry into Goose's config (macOS `~/.config/goose/config.yaml`, Windows `%APPDATA%\Block\goose\config\config.yaml`) without touching anything else, backing the file up first. `--check` shows what it would do and `--remove` unregisters it. The path must be absolute, because Goose starts the server from its own working directory.

**Any other stdio MCP client.** Transport `stdio`, command `node` (or the absolute path to a Node 22 binary), arguments the absolute path to `bin/forge-mcp.js`, no environment variables required. If you keep the bridge's data somewhere other than the default, set `FORGE_BRIDGE_HOME` to the same value for the client and for every `npm run agent-token` command.

**Check it works.** Ask your agent to call `forge_intel_agent_status`. It should show `configured: true`, the token's name, its scopes, the scopes it does not have, and `reachable: true`.

## Tools

| Tool                                         | Does                                                                                 | Scope                            |
| -------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------- |
| `forge_intel_agent_status`                   | What this token can and cannot do. Start here when a tool refuses                    | any                              |
| `forge_intel_portfolio`                      | Portfolios and holdings: quantity, cost basis, current value, allocation and profit  | `read:portfolio`                 |
| `forge_intel_theses`                         | Theses, what would confirm or invalidate each, and the engine's suggested status     | `read:thesis`                    |
| `forge_intel_alerts`                         | Alert rules, and optionally what recently fired                                      | `read:alerts`                    |
| `forge_intel_charts` and `forge_intel_chart` | The list of saved chart views, and one view in full with its drawings and indicators | `read:charts`                    |
| `forge_intel_watchlists`                     | Watchlists and their items                                                           | `read:watchlists`                |
| `forge_intel_evidence`                       | Evidence on one thesis, or your investigation receipts                               | `read:evidence`                  |
| `forge_intel_propose_write`                  | Proposes one change. Writes nothing                                                  | the matching `write:` scope      |
| `forge_intel_write_status`                   | Whether a proposal is proposed, approved, executed, failed, rejected or expired      | none (the token's own proposals) |
| `forge_intel_execute_write`                  | Runs an approved proposal, then reads the record back                                | the matching `write:` scope      |

Theses, alerts, chart views, evidence and receipts come back in pages of 20. Every read carries `licence.fields`, a map of each returned field to `yours` (your own entry), `allowed_with_attribution` (our calculation, such as `current_value` and `unrealized_pnl`) or `ask_first` (a provider figure, such as `current_price`, or a record that can carry one). `forge_intel_agent_status` and the write tools carry none. The republishing rule is on [Hosted MCP Server](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/hosted-mcp.md#licence).

## Propose and approve changes through the bridge

The bridge uses the same propose, approve, run and verify steps as the hosted server, described on [Agents and Agent Access](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/agent-access.md).

1. **Propose.** The agent calls `forge_intel_propose_write` with one of three changes: create an alert (`intel_create_alert`, needs `write:alerts`), add one annotation to a saved chart view (`intel_annotate_chart`, needs `write:charts`), or add one piece of evidence to a thesis (`intel_append_thesis_evidence`, needs `write:thesis`). An alert is proposed as a draft unless the agent sets `active: true`, and whether it is live is part of what you approve.
2. **Approve.** The request waits on the Agents page under **Waiting for your approval**, or in your terminal with `npm run agent-token -- pending`, which prints each proposal's target in words and its full plan hash. Approve with `npm run agent-token -- approve <proposal-id>` or reject with `npm run agent-token -- reject <proposal-id>`, signed in as you. A proposal expires 24 hours after it is made if nobody approves it, and an approval 24 hours after it is given if the agent does not run it.
3. **Run.** The agent polls `forge_intel_write_status`, then calls `forge_intel_execute_write` with the proposal id. For a chart annotation, if the saved view changed at the same moment, the write is refused as a conflict rather than overwriting your change, and the agent has to propose it again.
4. **Verify.** The server reads the record back and reports a write that cannot be found as failed, not as success. Your approval is used up either way. Running the same approved proposal again does not create a second alert, annotation or evidence item.

## Manage tokens from the command line

Creating, listing and revoking tokens and approving proposals act as you, so they need you signed in on that computer first:

```bash
npm run login
```

It asks for your Investor Intel email and password (press Enter to accept the suggested project address and key), and keeps only a refreshable session, in the same protected store as the token. Your password is never written to disk. Then:

```bash
npm run agent-token -- create --name "Laptop agent" --scopes read:portfolio,read:thesis --days 90 --save
npm run agent-token -- list
npm run agent-token -- revoke <token-id>
npm run agent-token -- pending
npm run agent-token -- approve <proposal-id>
npm run agent-token -- reject <proposal-id>
```

`create` prints the new token once; `--save` also stores it on this computer for the bridge, and without it you can paste the token on another computer with `set`. `--days` is 1 to 365 (default 90), and `npm run agent-token -- --help` lists every scope. `list` shows each token's id, state, last six characters, scopes, expiry and last use; `revoke` stops a token on its next request.

`set`, `status` and `clear` need no sign-in. `npm run agent-token -- clear` only forgets the token on this computer. It does **not** revoke it: revoke it as well if it should stop working everywhere.

None of these commands is a tool your agent can call. Creating a token, widening its scopes and approving a write stay in your hands.

## Limits

The bridge has its own limits per token, per minute: 120 reads, 20 proposals and 20 runs. Past those, the agent is told how long to wait. The hosted server's limits, including the daily allowance, are on [Hosted MCP Server](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/hosted-mcp.md#limits).

## Troubleshooting

| Symptom                                             | What to do                                                                                                                                                        |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forge_intel_agent_status` says `configured: false` | No token is stored for this OS user. Run `npm run agent-token -- set` as the user the client runs as                                                              |
| A tool refuses with a missing scope                 | The token lacks that scope. Create a token that carries it, and store it with `set`                                                                               |
| `Not signed in. Run "npm run login" first`          | A management command (`create`, `list`, `revoke`, `pending`, `approve`, `reject`) needs you signed in                                                             |
| The client does not list the tools                  | The path must be absolute and `node` must be on the PATH the client sees. Run `node bin/forge-mcp.js` in the bridge's folder: it should print `[forge-mcp] ready` |
| A token has been exposed                            | Revoke it on the Agents page or with `revoke`, then create a new one                                                                                              |
