> 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/agent-access.md).

# Agents and Agent Access

Agent access lets software you choose, such as Claude Code, Claude Desktop, Cursor, Goose or another MCP client, read your Investor Intel data and ask to make a small set of changes. You decide exactly what it can read, and nothing it wants to change happens until you approve that exact change.

The agent never signs in as you. It uses an **agent token**: a separate key you create for it, limited to the scopes you tick, that expires on its own and that you can revoke at any time.

## Who can use it

Agent access needs the **Starter plan or higher**. The plan is checked every time a token is used, not only when it is created, so if a workspace moves to a lower plan, its existing tokens stop working on their next request. The same applies if you leave the workspace or it loses Investor Intel access.

## Create a token

1. Open **Agents** in the Investor Intel sidebar (`/intel/agents`). The old address, **Settings > Agents** (`/intel/settings#agents`), links there.
2. Under **Create a token**, give it a name that says where it runs, for example "Laptop agent".
3. Choose how many days it lasts (1 to 365, default 90).
4. Tick what it may read, and optionally what it may ask to change. Ticking a write also ticks the read it needs, because every write is checked by reading it back.
5. Select **Create token** and copy it straight away. It starts with `tcfagt_`, **it is shown once**, and it cannot be shown again. Only a fingerprint of it is stored, so nobody, including us, can recover it later. The list afterwards identifies it by its last six characters.

You can have up to 10 live tokens per member per workspace. Use one token per machine or per agent, with the fewest scopes it needs, so revoking one does not affect the others.

## Limits, refusals and the end of a trial

The **Agents** page shows all of this for your workspace, read from the live plan.

* **Per minute:** on the hosted server each token may make 60 tool calls a minute, and 240 requests a minute in all (handshakes and tool lists included), on every plan that includes agent access.
* **Per day:** each token has its own daily allowance of tool calls, set by the plan (Trial 10,000, Starter 2,000, Pro 10,000, Elite no daily ceiling), resetting at midnight UTC. Each token on the Agents page shows its calls used today, and an agent can read the same figures with the `data_budget` tool.
* **429:** over a limit the server answers HTTP 429 with a `Retry-After` header in seconds (the wait for the per-minute window, or the seconds to midnight UTC for the daily allowance). The JSON-RPC error carries `retry_after_seconds`, `window`, `limit`, `used` and `resets_at`.
* **What counts:** a tool call is counted when it passes the per-minute check, before the tool runs, so a call refused for a missing scope, the plan or its arguments, or one that fails, still counts. Calls refused by the per-minute or daily limit do not count, and neither do `initialize`, `tools/list` and other protocol requests.
* **End of a trial or a plan change:** the plan is checked on every request. When a trial ends the workspace moves to Free, which has no agent access, and its tokens are refused with 403. They are not deleted: if the workspace chooses a plan with agent access before a token expires, the same token works again. A plan change takes effect on the next call.
* **Approvals:** requests to create an alert, annotate a chart or add thesis evidence wait on the Agents page under **Waiting for your approval**. A request waits 24 hours; an approval is good for 24 hours.
* **Live tokens:** up to 10 live tokens per member per workspace, on every plan that includes agent access. The plan cards on `/investors`, the plan table on `/intel/start` and Settings, and the Agents page all show the calls a day, the tool calls a minute and this token count.
* **Republishing figures:** you may republish figures Investor Intel calculates (`calculated_by: investor_intel`), including in a paid newsletter, with "Calculated by Investor Intel (thecontentforge.io/intel)". Figures from CoinMarketCap, CoinGecko and other providers need permission first (<support@thecontentforge.io>). Every hosted server result and every bridge read carries a `licence` field with this rule; see [Hosted MCP Server](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/hosted-mcp.md#licence) and the Agents page section **Republishing figures**.
* **No token yet:** the public demo server needs no account and no token. It serves the read tools that answer from stored captures on free plan surfaces, read only. See [Hosted MCP Server](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/hosted-mcp.md).

## Scopes

| Scope              | What it allows                                                                                                                                                                                               | On the hosted server                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `read:portfolio`   | Your portfolios and holdings: quantity, cost basis, current value, allocation and profit                                                                                                                     | No tool; use the local bridge                             |
| `read:thesis`      | Your written theses, what would confirm or invalidate each, and the engine's suggested status                                                                                                                | No tool; use the local bridge                             |
| `read:alerts`      | Your alert rules, whether each is live or a draft, and alerts that recently fired                                                                                                                            | `alerts_list`                                             |
| `read:charts`      | Your saved chart views, and the full drawings and indicators of one view                                                                                                                                     | No tool; use the local bridge                             |
| `read:watchlists`  | Your watchlists and the items, labels and notes on them                                                                                                                                                      | `watchlist_read`                                          |
| `read:evidence`    | Evidence recorded against a thesis, and your saved investigation receipts; on the hosted server also your Daily Briefs, Explain This answers and saved research, each with its confidence label and receipts | `daily_brief_read`, `explain_read`, `saved_research_read` |
| `write:alerts`     | Ask to create a price alert, or an alert on any other trigger the Alerts page offers (needs `read:alerts`)                                                                                                   | `alert_create`, `alert_create_rule`                       |
| `write:charts`     | Ask to add one annotation to a saved chart view (needs `read:charts`)                                                                                                                                        | No tool; use the local bridge                             |
| `write:thesis`     | Ask to add one piece of evidence to a thesis (needs `read:thesis`)                                                                                                                                           | No tool; use the local bridge                             |
| `write:watchlists` | Add one item to a watchlist, making "My Watchlist" on a first add (needs `read:watchlists`)                                                                                                                  | `watchlist_add`                                           |
| `write:research`   | Save one note to your saved research (needs `read:evidence`)                                                                                                                                                 | `save_research_note`                                      |

The market and tokenized real-world-asset tools need no scope. Reads return a fixed list of fields for each kind of record. Internal bookkeeping, other members' data and the token store are never part of a read.

A token cannot create, list or revoke tokens, and cannot approve anything. Those need you, signed in.

## Connect a client

Point any MCP client at the hosted server and pass the token as a bearer header. Nothing is installed, and it is where the market and tokenized real-world-asset tools live. See [Hosted MCP Server](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/hosted-mcp.md), or copy the ready-made lines from the **Agents** page, under **Connect your agent**. There, **Test this token** checks a token without spending a daily call and shows the request it sent (the token cut to its first characters), the status, the headers and the number of tools; **Test and run whoami** also shows the token's scopes and expiry, your plan and the calls left today, for one call. The **Agents** page also keeps a three-step setup checklist, ticked from your own tokens.

The same token also works through the [Local Agent Bridge](https://thecontentforge.gitbook.io/thecontentforge-docs/investor-intel/local-agent-bridge.md), a second, local way to connect that is the only way to reach the Portfolio, Theses and Charts scopes and the Annotate charts and Add thesis evidence writes.

**The agent API.** Software that is not an MCP client can send the same token to `https://api.thecontentforge.io/functions/v1/intel-agent-api` (the first address, `https://andrimdaxlxcqgqdqrbz.supabase.co/functions/v1/intel-agent-api`, still works) as `POST` with a JSON body naming an `operation`. The operations are `whoami`, `read_portfolio`, `read_theses`, `read_alerts`, `read_charts`, `read_chart`, `read_watchlists`, `read_evidence`, `propose_write`, `execute_write` and `plan_status`, which the local bridge uses, and `read_candles`, `export_series` and `exit_quote`, which take the same arguments as the hosted tools `get_candles`, `export_series` and `exit_quote` and give the same answer. `exit_quote` is a live quote and uses one of the member's exit quotes for the day. Each token may make 120 reads, 20 proposals and 20 runs a minute here. A token can never create, list or revoke tokens or approve anything through it.

Never paste a token into a chat with the agent, a shared document or a repository. If a token has been exposed, revoke it and create a new one.

## How changes are proposed and approved

An agent can never change your data in one step, except the two small direct writes under [Retrying safely](#retrying-safely). Every other change goes through propose, approve, run, verify.

1. **Propose.** The agent asks for one change: an alert (on the hosted server `alert_create` for a price level, or `alert_create_rule` for any other trigger), an annotation on a saved chart view, or evidence on a thesis. The server checks the token has the matching write scope, checks the request with the same rules the app uses when you do it yourself, and works out for itself what the change touches: the alert's asset, or the saved view or thesis it reads back from your workspace. Anything the agent says about the target, the workspace or the record id is ignored. Nothing is written yet. An alert is proposed as a draft unless the agent explicitly asks for a live one, and the proposal says which.
2. **Approve.** The request appears on the **Agents** page under **Waiting for your approval**. Each one shows:

   * a sentence saying what it will do,
   * its risk level (an alert is level 2 because it can notify you; an annotation or evidence is level 1),
   * **What it touches**, the target the server worked out,
   * **Request fingerprint**, a short form of the plan hash, with a button to copy the full hash,
   * the values that will be written.

   The plan hash is a SHA-256 fingerprint of the tool, the target, the values and the risk level. It does not cover the display sentence, so rewording changes nothing. Your approval is bound to that hash: if the proposal differs in any way that matters, for example a draft alert becoming live or a different price, the hash no longer matches and your approval does not apply. The agent sees the same hash in its proposal, so you can compare the two if you want to be certain you are approving what the agent asked for.

   Select **Approve this request** or **Reject**. A proposal expires 24 hours after it is made if nobody approves it, and an approval expires 24 hours after it is given if the agent does not run it.
3. **Run.** The agent checks the proposal's state (`write_status` on the hosted server) and then runs it (`write_run`). Just before writing, the server checks again that the token is live, still has the scope, you are still a member with access, the approval exists and has not expired, and the approval's hash equals the proposal's hash. It then recomputes the hash from the stored proposal and refuses if it does not match. The write goes through the same checks the app applies to your own edits.
4. **Verify.** After writing, the server reads the record back and confirms it is there, in your workspace, and says what you approved. The result is saved as a **verification record** with what was expected, what was observed, and whether it passed. A write that reported success but cannot be found is reported to the agent as failed, not as success. Your approval is used up by the attempt either way, so a failed write cannot be quietly retried on the same approval.

Running the same approved proposal again does not create a second alert, annotation or evidence item.

## Review what your agent did

* **Recent calls, per token.** Each token on the Agents page has a **Recent calls** disclosure: one row per tool call, newest first, with the time, the tool, whether it was answered, refused or failed and why, how long it took and how large the answer was, fifty at a time with **Older calls** for the rest. It is read only when you open it. Tool arguments are never recorded, so they are not shown.
* **What your agents made.** A section of the Agents page lists every alert rule an agent proposed and you approved, and every note an agent saved, each with the name of the token that made it. The Alerts page names those rules above its rule list, and links back.

## Retrying safely

`watchlist_add` and `save_research_note`, the two writes that do not wait for approval, take an optional `idempotency_key` (8 to 80 letters, digits, `.`, `_`, `:` or `-`). The same key with the same arguments within seven days returns the first answer and writes nothing again, so a scheduled job can retry a call that timed out. The same key with different arguments is refused (`idempotency_key_reused`). Without a key, `watchlist_add` still never adds the same asset twice to one list: the second call answers `already_on_list`.

`watchlist_add` makes a watchlist called "My Watchlist" when the workspace has none, resolves the asset you name (a catalogue key or an exact ticker) and attaches it to the same asset identity the app uses, so the item behaves like one added by hand.

## Developer onboarding

Choosing **Connect my own agent** as the answer to "What are you here to do?" in onboarding skips the investor questions (they shape the app's own writing, not what an agent reads) and shows three steps instead: create a token on the Agents page, test it there, and make a first `whoami` call, with a sample prompt for a weekly newsletter agent. Nothing is invented for the skipped questions: they are saved unanswered and can be answered later in Settings.

## Revoke access

Open the **Agents** page and select **Revoke** on the token. It stops working on its next request.

Tokens also stop working on their own when they expire, when you leave the workspace, or when the workspace's plan no longer includes agent access. To stop a pending change instead of a whole token, reject it.
