Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 42 additions & 6 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,9 @@ endpoint. `authConfig` (OAuth and other stored credentials) is never exported:
re-authorize the connector after importing it. Secret environment variables
and headers are included only for admins signed in to the dashboard or using a
`MANAGEMENT_ADMIN` key. For other roles, and for any `MANAGEMENT_READ` key, they
are empty and named in `maskedEnvVars` / `maskedHeaders`. Per-tool `useProxy`, annotation
are empty and named in `maskedEnvVars` / `maskedHeaders`, and a secret still written in an HTTP
base URL (a webhook token, a key, `user:password@`) shows as `********`; see
[Secrets typed into the base URL](connectors/rest.md#secrets-typed-into-the-base-url). Per-tool `useProxy`, annotation
overrides and role access are not exported.

```bash
Expand Down Expand Up @@ -405,6 +407,10 @@ Export your key as `AMCP_MCP_API_KEY` (or `AMCP_ACCESS_TOKEN` when the server op
| GET | `/api/roles/:id/tools` | List tool access for a role |
| PUT | `/api/roles/:id/tools` | Set tool access whitelist |
| PUT | `/api/roles/:id/tools/:toolId/rate-limit` | Update rate limits on an existing tool grant |
| GET | `/api/roles/members` | List members with every MCP role they hold and the connectors those roles reach |
| GET | `/api/roles/assignments/:userId` | List a member's MCP roles, with where each comes from |
| PUT | `/api/roles/assignments/:userId` | Replace a member's manual MCP roles |
| PUT | `/api/roles/assign/:userId` | Deprecated: set one MCP role. Use `PUT /api/roles/assignments/:userId` |

### Create Role with Tool Whitelist

Expand All @@ -423,12 +429,42 @@ curl -s -X PUT http://localhost:4000/api/roles/$ROLE_ID/tools \
-d '{"toolIds": ["tool-id-1", "tool-id-2", "tool-id-3"]}'
```

### Assign roles to members

A member can hold several MCP roles and may call the **union** of their tools:
each role adds tools, none takes any away. A role comes from one of two
sources:

- `manual`: set by an admin, under **Settings → Roles** or with
`PUT /api/roles/assignments/:userId`.
- the single sign-on group sync (for example `entra`): set by the
provider's role mappings ([SSO guide](sso.md#3-map-directory-groups-to-roles)).
Change these in the mappings, not on the member.

`PUT /api/roles/assignments/:userId` replaces only the member's **manual**
roles in your workspace; roles from group sync stay.

```bash
curl -s -X PUT http://localhost:4000/api/roles/assignments/$USER_ID \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"roleIds": ["'$ROLE_ID'"]}'
```

`GET /api/roles/members` returns every member of your workspace with all their
roles (`roles[]`: `roleId`, `roleName`, `source`, and `global` for a grant that
applies in every workspace) and `connectors`, the connectors those roles reach.
`connectors` is `null` when roles do not limit the member: a workspace ADMIN,
or a member with no role while no role of the workspace has a tool list.
`GET /api/users` also returns all roles of each member in `mcpRoles`; its
`mcpRoleId` and `mcpRole` fields are deprecated and hold one role at most.

### Per-tool rate limits

An administrator can set optional minute and hour limits on an existing
role/tool grant. The editor UI is planned separately; configure limits through
the API for now. `GET /api/roles/:id/tools` returns `callsPerMinute` and
`callsPerHour` on each grant.
role/tool grant, under **Settings → Roles → Manage tools** or through the API.
`GET /api/roles/:id/tools` returns `callsPerMinute` and `callsPerHour` on each
grant.

```bash
curl -s -X PUT "http://localhost:4000/api/roles/$ROLE_ID/tools/tool-id-1/rate-limit" \
Expand Down Expand Up @@ -489,8 +525,8 @@ call, so cached presence never replaces the caller's current role policy.
| PUT | `/api/admin/settings/member-visibility` | Admin: set `{ "mode": "open" }` or `{ "mode": "restricted" }` |

In a workspace set to `restricted`, a member who is not an admin gets only
their own calls from the audit endpoints, only the connectors and MCP servers
their roles reach, and 404 for the others. A connector they can see but do not
their own calls from the audit endpoints, only the connectors their roles
reach, only the MCP servers they own, and 404 for the others. A connector they can see but do not
own comes back in a reduced view marked `memberView: true`: `id`, `name`,
`type`, `icon`, `isActive`, `credentialScope`, `setupStatus`, `authStatus`,
`authStatusCode`, and of each allowed tool `id`, `name`, `description` and
Expand Down
48 changes: 48 additions & 0 deletions docs/connectors/rest.md
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,54 @@ curl -s -X PUT http://localhost:4000/api/connectors/$CONNECTOR_ID/env-vars \

Use `{{VAR_NAME}}` in endpoint mappings. Parameters matching env var names are automatically stripped from the tool schema.

### Secrets typed into the base URL

Some services put the credential in the address itself: a Bitrix24 inbound webhook
(`https://portal.bitrix24.com/rest/1/<code>/`), a Slack, Discord, Microsoft Teams, Zapier or Make
webhook URL, a Telegram bot URL (`https://api.telegram.org/bot<token>`), a key in the query string
(`?api_key=…`, `?token=…`, `?sig=…`), or `https://user:password@host`. Whoever holds such a URL can
use it like a password.

When you save a REST, GraphQL, SOAP, OData or MCP connector with such a base URL, AnythingMCP moves
only the secret part into an encrypted variable and stores the rest of the URL with a reference:

```
typed: https://portal.bitrix24.com/rest/1/k2bx…vqgo/
stored: https://portal.bitrix24.com/rest/1/{{BITRIX_CRM_WEBHOOK_TOKEN}}/
```

- The variable is named after the connector (`<NAME>_WEBHOOK_TOKEN`, `<NAME>_PASSWORD`,
`<NAME>_API_KEY`, `TELEGRAM_BOT_TOKEN`) or reuses a variable that already holds the same value.
Its value is encrypted at rest and never returned by the connector API, to admins neither (only an
admin export with secrets carries it, like every other variable); the dashboard shows it as set. The save answers with `secretsMoved` and `secretsNotice`, naming the variable,
never the secret.
- Calls are unchanged: every call replaces `{{VAR}}` in the base URL with the variable's value as
stored, so the request goes to exactly the URL you typed. To change the secret, edit the variable,
or type the full URL again.
- The host and the rest of the path stay readable, so the connector page, error hints and logs still
show where the connector points.
- Headers and tool paths get the same treatment (`Authorization: Bearer <token>` becomes
`Bearer {{<NAME>_TOKEN}}`).

Connectors saved before a rule existed keep the secret in the stored base URL until they are
saved again. Until then the API shows it as `********`
(`https://portal.bitrix24.com/rest/1/********/`); saving the form with the URL as shown keeps the
stored secret and moves it into a variable, and a URL edited around `********` is refused, so type
the full address again. The backend also moves these at every start, the same way a save does,
except for long random path segments with no known shape (a save moves those and says so; the
start-up pass leaves them alone). This needs no setting and works the same on AnythingMCP Cloud and
self-hosted. The backend log shows the result with connector ids and counts, never a URL:

```
Base URL secrets: secrets of 2 connectors moved into encrypted variables (cm1…, cm2…); 0 left as is; 0 failed
```

"Left as is" are connectors that were saved while the pass ran; the next start checks them again.
"Failed" names connectors whose variables could not be decrypted (a changed `ENCRYPTION_KEY`) or
written; they stay unchanged, still masked in the API, and the next start tries again.
`scripts/secret-literals/report.ts` lists what is left, and `repair.ts` also cleans tool paths,
headers and tool names (dry run by default, with a backup table before `--apply`).

---

## Example: Full REST API Setup
Expand Down
Loading
Loading