# Agent Builder MCP server

Agent Builder exposes an authenticated **MCP server** (Model Context Protocol) so external AI clients and coding agents — Claude Code, Claude Desktop, Codex, or any MCP-compatible client — can create, inspect, debug and test workflows in your workspace, and manage credential records, from outside the app.

- **Endpoint**: `<your-backend-url>/api/v1/mcp-server`
- **Transport**: MCP streamable HTTP (stateless JSON-RPC)
- **Authentication**: `Authorization: Bearer <token>` — a personal API token (recommended) or a login JWT

## 1. Create a personal API token

API tokens are long-lived credentials scoped to your account. Create one (the secret is displayed **once**):

```bash
curl -X POST <backend>/api/v1/api-tokens/ \
  -H "Authorization: Bearer <your-login-JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "expires_in_days": 90}'
```

The response contains `"token": "abp_…"` — store it in a safe place. You can list your tokens (`GET /api/v1/api-tokens/`, metadata only) and revoke one at any time (`DELETE /api/v1/api-tokens/{public_id}`).

## 2. Connect a client

**Claude Code** (CLI):

```bash
claude mcp add --transport http agent-builder \
  <backend>/api/v1/mcp-server \
  --header "Authorization: Bearer abp_…"
```

or with a project `.mcp.json` (keep this file out of git — it contains your token):

```json
{
  "mcpServers": {
    "agent-builder": {
      "type": "http",
      "url": "<backend>/api/v1/mcp-server",
      "headers": { "Authorization": "Bearer abp_…" }
    }
  }
}
```

Any other MCP client works the same way: streamable HTTP endpoint + the Authorization header. To work inside a **team workspace**, also send the `X-Workspace-Team: <team-public-id>` header.

## 3. Available tools

| Area | Tools |
| --- | --- |
| Workflows | `list_workflows`, `get_workflow`, `create_workflow`, `update_workflow`, `validate_workflow`, `test_workflow` |
| Executions | `list_executions`, `get_execution` |
| Platform knowledge | `list_node_types`, `get_node_type`, `search_docs` |
| Credentials | `list_credentials`, `create_credential`, `start_credential_oauth`, `assign_credential_to_node`, `test_credential` |

Workflow graphs use the editor's format: `nodes: [{id, type, position, data}]` and `edges: [{source, target, sourceHandle?}]`. Ask the server itself for details: `search_docs("templates")`, `get_node_type("agent")`.

## 4. Example

Ask your connected agent, for instance:

> "Create a workflow that monitors incoming support emails, classifies each request, generates a suggested response and sends urgent issues to Slack. Create any missing credential records and tell me which authorization steps I need to complete."

The agent will inspect the node registry, build and validate the workflow in your workspace, create credential records, and hand you the OAuth authorization links to finish in your browser.

## Security model

- **Authentication is mandatory** — every call requires a valid Bearer token; unauthenticated requests get 401.
- **Tokens are hashed at rest** (SHA-256). The secret is shown once at creation; afterwards only a display prefix is stored. Tokens support expiry dates and immediate revocation.
- **Workspace isolation** — the server only ever operates on workflows and credentials the authenticated user can access; team workspaces enforce team roles.
- **Secrets never leave the server** — credential tools return metadata only (name, provider, status, expiry, usage). Secret values are write-only: they are encrypted (Vault or Fernet) on arrival and never serialized back, to MCP clients or anyone else.
- **OAuth stays server-side** — `start_credential_oauth` returns an authorization URL for the user's browser; access and refresh tokens are stored server-side, never sent to the MCP client.
- **Auditability** — credential operations are written to the credential audit log.

Recommendations: expose the backend over **HTTPS** in production, create one token per client with an expiry, revoke unused tokens, and never commit tokens (add `.mcp.json` to `.gitignore`).

---

*Source: https://agentbuilder.systalink.sn/docs/mcp-server — human documentation.*
*Other language: [/docs-md/fr/mcp-server.md](/docs-md/fr/mcp-server.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*