# Connect your own agent over MCP

> Give Claude Code, Claude Desktop or any other MCP client a token of its own, and it works in sourcesignal as you, with only the scopes and projects you choose. Looking for an API? The agent connection over MCP is on every plan, with a token from Settings, Agents; a custom API for your own systems is an Enterprise conversation.

sourcesignal documentation, Spot and agents. Updated 2026-10-22. The page for people: https://www.sourcesignal.ai/docs/spot-and-agents/connect-your-own-agent-over-mcp. Every article: https://www.sourcesignal.ai/llms.txt

Settings, Agents is where you make the tokens your own agent connects with. A token lets an MCP client read your projects, ask Spot and prepare work in your name, with only the scopes you check and the projects you pick. Every change it asks for waits for you as a card, unless your setting under Settings, Agents applies that kind of change at once, so you stay the one who decides.

Use it when an agent outside the app, such as Claude Code in your terminal, should answer questions about a project or line up changes for you. Inside the app, [Spot](https://www.sourcesignal.ai/docs/spot-and-agents/spot-the-in-app-agent.md) does the same work from its panel.

## How to create a token

1. Open Settings, then Agents, and press "New token". Any member of the account can make one.
2. Under "Name", say where the agent lives, for example "Claude Code on the laptop". The name is how you tell tokens apart when you revoke one later.
3. Optionally, fill in "What you call the agent", for example "Dana's assistant". It is printed on every card the agent asks you for, beside what the agent says about itself.
4. Check the scopes the agent needs. Every scope you may hold starts checked, so uncheck the rest. A token with no scope is refused.
5. Under "Projects", choose "All your projects" or "Only the ones you check".
6. Pick an "Expiry": "No expiry", "30 days", "90 days" or "365 days".
7. Press "Create token".

The next screen shows the secret with a "Copy" button. Copy it now and store it somewhere safe: it is shown only once. While the secret is on screen, "Done" is the only way out of the dialog.

> **Heads up:** If you lose the secret, there is no way to see it again. Revoke the token and create a new one.

## Choose scopes

A scope is what the token may do. Each one appears in the dialog with its label, a one-line description and its key.

| Scope | Key | What the agent may do |
|---|---|---|
| Read your projects | `project:read` | Read the projects you can open: the pages the engines cite, the deck, outreach, tracking and setup. Read only. |
| Suggest rules and a focus | `project:steer` | Suggest steering rules, a focus for the deck and the daily decision budget. Each one waits for you to apply it. |
| Make changes in your projects | `project:work` | Make changes in your projects, such as parking pages, researching contacts or setting deck rules. Each change waits as a card for you to apply, unless your setting in Settings, Agents, or a mandate you approved, applies that kind of change at once. An email or a post goes at once only where you set "Emails and posts to publishers" to Apply at once, never under a mandate, and through the same checks as yours. Never billing, members or access, and never a permanent delete. |
| Ask Spot | `spot:ask` | Ask Spot for plans and answers about your projects. Each answer uses the account's AI allowance, which no plan limits today. |
| Read the account | `org:read` | The whole account at once: every project and how each is doing, members, mailboxes and what the account used this month. Owners and admins only. |

- Keep "Read your projects" on almost every token. Your agent's first call, which tells it who it works for and which projects it reaches, needs it.
- "Read your projects" also lets your agent compare the projects you can open side by side and read the plan's limits with what is used, the same numbers Settings, Billing shows every member. A token limited to named projects reads only those projects and no plan limits.
- Questions through "Ask Spot" count toward the 30 questions an hour Spot answers per person.
- The [Tool reference](https://www.sourcesignal.ai/docs/spot-and-agents/agent-tool-reference.md) lists every tool each scope opens.
- Scopes are checked again on every request. If you leave the account, the token stops working. If an owner or admin becomes a member, the token loses "Read the account".

[Agent scopes and limits](https://www.sourcesignal.ai/docs/spot-and-agents/agent-scopes-and-limits.md) covers each scope in detail and the mandates an agent can ask for.

## Limit the token to some projects

"All your projects" reaches every project you can open, including projects added later. "Only the ones you check" opens a list of your projects: check at least one, and up to 100.

- The reach is fixed once the token is made. To change it, make a new token and revoke the old one.
- A token limited to named projects can never read the whole account, even with "Read the account".
- When your agent asks about a project outside its reach, it is told the token is limited to other projects.

> **Tip:** Make one token for each client and machine. Revoking one then never cuts off the others, and "Last used" tells you which agent is still active.

## Connect your client

The endpoint address is `https://www.sourcesignal.ai/api/mcp`. It speaks MCP over HTTP (streamable HTTP) and takes the secret as a bearer token, so an MCP client that sends `Authorization: Bearer <secret>` on every request can connect. There is no SSE endpoint. The secret screen fills the address and your secret into ready-made snippets, each with its own "Copy" button.

Clients that run on your computer or a server, such as Claude Code, connect from anywhere. A client that runs inside a web page connects only from sourcesignal's own site or from Claude on the web (`claude.ai` or `claude.com`), where Claude's connectors run. A page on any other site is refused before the token is read. [How the door answers](https://www.sourcesignal.ai/docs/spot-and-agents/how-the-door-answers.md) covers this and the other rules every request meets.

### Claude Code

Copy "Claude Code: one command" and run it in the folder you want the agent to work from:

```
claude mcp add --transport http sourcesignal https://www.sourcesignal.ai/api/mcp --header "Authorization: Bearer <secret>"
```

Claude Code sends the header on every call and never prompts you to sign in. A failed connection means the token is wrong, revoked or expired.

### A shared project file

For a repository other people use, copy ".mcp.json: for a shared project". It reads the secret from a shell variable, so the file can be committed without it. The dialog uses one fixed variable name in both the file and the export line; the example below shows it as a placeholder:

```json
{
  "mcpServers": {
    "sourcesignal": {
      "type": "http",
      "url": "https://www.sourcesignal.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${YOUR_TOKEN_VARIABLE}"
      }
    }
  }
}
```

Press "Copy export line" and run that line in the shell that starts your agent. The dialog fills in the real line for you; it looks like this:

```
export YOUR_TOKEN_VARIABLE="<secret>"
```

### Claude Desktop

Claude Desktop connects through a custom connector. Add one with the endpoint address, no OAuth sign-in, and one request header whose value is your secret:

```
x-api-key: <secret>
```

The connector accepts only some header names, so use `x-api-key` (or `x-auth-token`). If you use `Authorization` instead, the value must be the word Bearer, a space, then the secret.

### Check that it works

The server tells your agent to begin with a call named `start` and to repeat its connected line to you, so you see at once that the connection works. The line reads, for example, "Connected to sourcesignal as Dana (owner) at Acme, on the Growth plan. 3 projects are in reach." The same answer says who the agent works for, your role, the account and the projects the token reaches. That first call also stamps the token's "Last used": reload Settings, Agents to see the time.

## What happens after you connect

- Most tools read, answer at once and use none of the account's AI allowance. Six do use it: asking Spot (`spot_ask`), asking for plan options (`spot_plan`), reading a steering sentence (`steer_compile`), suggesting keywords from your prompts (`keywords_suggest`), suggesting sections of your outreach prompt (`outreach_prompt_suggest`) and suggesting a sequence template's emails (`sequence_template_suggest`). No plan limits that allowance today: the work is counted for the account, not capped.
- Asking Spot and asking for plan options also count toward your 30 questions an hour, and may answer with a result your agent checks back on with `status`. See [How the door answers](https://www.sourcesignal.ai/docs/spot-and-agents/how-the-door-answers.md).
- Every change your agent prepares becomes a card, unless your setting applies that kind of change at once ("Apply at once or ask first", under Settings, Agents), where it shows as applied with "Take back" for a day. It waits in the Spot panel on that project and on Settings, Agents, under "Waiting for you". Nothing happens until you decide, and a card you leave expires after 24 hours. See [Change cards: apply and undo](https://www.sourcesignal.ai/docs/spot-and-agents/change-cards-apply-and-undo.md).
- Your agent can hand you a link straight to each card. In Claude, ChatGPT, VS Code and other agent apps that show interactive cards, the card also appears in the chat with "Open in sourcesignal". Applying it always happens here, in your own signed-in session.
- Under a mandate you approve, the agent may make the changes it names on its own, by name or by kind, within the decisions and paid work a day you set and until the mandate ends. A mandate never sends an email or a post.
- Your agent knows your plan's room. `start` and the project brief tell it what is used of each limit (tracked prompts, AI engines per project, projects, mailboxes), what the plan leaves out and what the next plan would lift, in the same numbers Settings, Billing shows. When an answer is thin for that reason, for example because every tracked prompt is in use, it is asked to tell you so in one line and name the plan that lifts it. It never changes your plan: that stays yours, in Settings, Billing. See [How the door answers](https://www.sourcesignal.ai/docs/spot-and-agents/how-the-door-answers.md).
- Your agent sends a pitch or a reply only where your "Emails and posts to publishers" row applies at once, never under a mandate, and through the same checks as your own sends. It never pays anyone, never touches billing, members or access, never connects a mailbox, and never claims a win or confirms a placement without you.
- Questions your agent asks Spot appear in your threads, titled "Your agent asked: …".

## Expiry and revoking

- Expiry is counted from when you create the token. "No expiry" works until you revoke it.
- An expired token cannot be extended. Create a new one and give your client the new secret.
- To revoke, press "Revoke" on the token's row and confirm. The agent using it stops working immediately, and this cannot be undone.
- A revoked token stays in the list as "Revoked", for the record. An expired one stays as "Expired".
- Revoking a token also ends its mandates. A mandate request still waiting can then only be declined.
- To take away only an agent's standing permission, press "End" on its mandate instead. From its next request the agent can read and ask, no more.

## The token list

"Agent tokens" counts your tokens (for example "2 active of 3"). Each row shows the name with what you call the agent under it, the first 12 characters of the token, its scopes and project reach, "Last used", the expiry, the day you made it and its status: "Active", "Revoked" or "Expired". On a phone, each token is a card of its own.

Reads are not logged one by one. "Last used" updates at most once a minute, and "Never" means no agent has used the token yet.

## When the connection fails

- **The client is refused.** The token is wrong, revoked or expired, or you no longer hold the role its scopes need, for example after you leave the account. Check its status in the list and create a new token if needed. The answer is a plain refusal, never a sign-in page.
- **Your client reports a 404 at `/mcp` or `/sse`.** Some clients retry those default addresses after a first attempt fails. Neither is the endpoint. Both answer with a short message that names `/api/mcp` as the real one and says there is no SSE endpoint. Check that your address ends in `/api/mcp`, then check the token.
- **Claude Desktop cannot connect.** The secret is usually missing from the request. Check the header name, and that the connector is not set to sign in with OAuth.
- **A client in a web page cannot connect, while Claude Code can.** The endpoint refuses web pages on any site other than sourcesignal's own and Claude on the web, before it reads the token. The client usually reports that it cannot reach the server. Use a client that runs on your computer, such as Claude Code, or a Claude connector.
- **Your agent is told to slow down.** The endpoint answers up to 120 requests a minute per token. Wait a moment and try again.

## Related

- [Agent scopes and limits](https://www.sourcesignal.ai/docs/spot-and-agents/agent-scopes-and-limits.md): Your agent works as you, with your plan's limits and no more. Every change it prepares waits for you, unless your setting under Settings, Agents applies that kind of change at once or a mandate you approved lets it make that change on its own.
- [How the door answers](https://www.sourcesignal.ai/docs/spot-and-agents/how-the-door-answers.md): What your own agent meets when it calls sourcesignal over MCP: one address, the token on every request, the limits on each call, long answers in parts and slow work it checks on later.
- [Tool reference](https://www.sourcesignal.ai/docs/spot-and-agents/agent-tool-reference.md): Every tool your own agent can call over MCP, grouped by the scope that opens it, with what each one does, how it answers, the recipes your agent can follow and the documentation it reads there as resources.
- [Change cards: apply and undo](https://www.sourcesignal.ai/docs/spot-and-agents/change-cards-apply-and-undo.md): Every change Spot or your own agent prepares reaches you as a change card, unless your setting under Settings, Agents applies that kind of change at once. A card changes nothing in your project until you press Apply, and many changes can be undone for 10 minutes.
- [Spot, the in-app agent](https://www.sourcesignal.ai/docs/spot-and-agents/spot-the-in-app-agent.md): Spot is the panel you open on any page to ask about a project in plain words. Its answers come from your own data, and a change it prepares waits as a card for you to decide, unless your setting applies that kind of change at once.
- [Security and privacy](https://www.sourcesignal.ai/docs/trust/security-and-privacy.md): How sourcesignal protects your account, keeps each organization's data separate, uses AI and handles the accounts you connect, with links to the Privacy Policy and Terms.