# ActAs MCP quickstart

ActAs gives AI agents a persistent identity, email inbox and scoped credentials.
Connect remotely over Streamable HTTP at https://actas.dev/mcp, or use the
MIT-licensed local stdio client from npm: https://www.npmjs.com/package/actas .
Public source: https://github.com/fray-agents/actas-mcp .

## Before you start

- Node.js 22 or newer, with npm/npx available to your MCP client.
- An ActAs Pro subscription: US$12/month or US$120/year. No free tier.
- Create an identity at https://actas.dev/app and assign its inbox and resources.
- In the identity Access tab, choose the minimum permissions and resources, then
  download its private connection JSON. Keep it outside your repository.

## Claude Desktop and Cursor

### Remote connection

In a client that supports Streamable HTTP with bearer headers, add
https://actas.dev/mcp and configure the Authorization header as `Bearer` followed
by the token from your private ActAs identity connection. Use your client's
protected credential settings; never put the token in the endpoint URL, a prompt
or a checked-in configuration. The endpoint accepts scoped identity and workspace
management connections; it does not accept browser cookies. No npm install is
needed. OAuth is not currently offered.

The remote endpoint lists the same 19 tools as the stdio client. Every API call
still checks the connection's current grants. Browser signup/login steps need a
local browser adapter. Executing registered local consumers and receiving private
verification-value handles return `needs_local_runtime` remotely; use the local
client for those operations. Remote MCP does not operate your local browser.

Stored passwords and TOTP codes are withheld by default. If you explicitly want
`actas_vault_login` or `actas_totp_code` to return secret values to your remote
client, configure the additional header `ActAs-MCP-Secret-Output: allow`.
Existing reveal scopes and vault grants are still required. Your client or hosted
connector may retain these values in chat history; prefer the local runtime when
you do not want a provider to receive them. Sign-in codes returned by
`actas_inbox_wait_for_code` also enter the client's results and history.

Workspace management tokens additionally require `ActAs-MCP-Management: allow`.
They can close accounts and remove domains within their grants. Prefer a narrowly
scoped identity connection for routine use.

### Local stdio connection

Add this to your client's MCP configuration. Replace the placeholder with the
absolute path to your private connection file. On Windows, use forward slashes
in the path; if needed use npx.cmd as the command.

```json
{
  "mcpServers": {
    "actas": {
      "command": "npx",
      "args": ["-y", "actas@0.4.0", "mcp"],
      "env": {"ACTAS_CONNECTION_FILE": "/absolute/path/to/actas-identity.json"}
    }
  }
}
```

Restart your MCP client after saving. The thin `actas-mcp@0.4.0` npm alias starts
the same server. You can also install once with:

```sh
npm install -g actas@0.4.0
actas mcp
```

For the global install, configure command `actas-accounts-mcp` with the same
ACTAS_CONNECTION_FILE environment variable. A stdio server waits for MCP input;
an idle terminal does not mean it failed.

For a direct download, use https://actas.dev/actas-mcp.tgz . A local checkout is
not required. Its MIT source is at https://github.com/fray-agents/actas-mcp .

## Check the connection

Ask your client to list ActAs tools, then use `actas_account_list` to inspect
account mappings within the connection's permissions. The client exposes 19
tools; available actions still depend on the connection's grants. No tool output
is proof that a third-party account has been registered or verified.

## Permissions and sensitive output

Some tools return granted credentials, messages or verification codes to the
authorized agent. Grant only what it needs. Do not put connection contents in
prompts, URLs, logs or source control. Never upload your connection file to a
directory or public MCP inspector. Revoking the client in ActAs Access stops
future API requests. Read access does not grant sending permission.

## Troubleshooting

- Command not found: make Node.js 22+ and npx available on the MCP client's PATH,
  or use their absolute executable path.
- Connection-file error: replace the placeholder with an existing absolute path
  and confirm the file belongs to the intended identity.
- Access denied: check the connection's action and resource grants in ActAs.
- Stdio startup: keep stdout for MCP messages; use your client's MCP logs to
  diagnose errors, without sharing credentials or message contents.

Documentation: https://actas.dev/docs#mcp
Machine-readable configuration: https://actas.dev/mcp.json
Remote endpoint: https://actas.dev/mcp (Streamable HTTP; bearer token required)
Agent guide: https://actas.dev/llms.txt
Pricing: https://actas.dev/pricing