Integration types
Connectors, tools & grants
Connector kinds (MCP server, database, remote agent, HTTP API), connections and health states, default-deny grants, approval policies and the five-step path from "Choose" to "Done".
A connector is how Agentic Workforce ME reaches one of your systems — its transport, its authentication and the tools it exposes.
A connector describes an external system Agentic Workforce ME can act on: an MCP server, a database, a remote agent or an HTTP API. It is a definition, not a login. To use it, an administrator adds a connection — encrypted credentials with a live health state — and Agentic Workforce ME discovers the tools the system exposes. Nothing is callable until a grant allows a specific agent or org unit to use a specific tool, and sensitive tools can be placed behind an approval policy so a named person decides before the call runs.
Three nouns, then, and they are worth keeping apart: the connector (a definition of a system and how to reach it), the connection (one set of encrypted credentials for it, with a live health state) and the tools it exposes, each of which an agent may use only through a grant. In the console all of them live on Integrations (/tools).
Connector kinds
Four kinds, one gateway. MCP is the transport for systems you host or buy; databases are one connector kind beside it, not a separate category; a remote agent is consumed exactly like a tool; an HTTP API credential serves workflow nodes rather than agents.
| Kind | How the platform reaches it · where the credential lives | Tools |
|---|---|---|
MCP server/v1/mcp-servers | Streamable HTTP (transport: http) to an endpoint you host, or a local process (stdio) deployed by platform operations. Auth kinds none, api_key (X-Api-Key), bearer, oauth (a static token).Credential: A connection ( /v1/connections), tenant-wide or scoped to an org node. | Whatever the server lists in tools/list; names are matched as <tool>, <server-slug>.<tool> or prefix.*. |
Database (Postgres, SQL Server, Oracle)/v1/connectors | Direct driver connection from the platform (driver: postgres | mssql | oracle) with allow-lists, max_rows and a statement timeout. MySQL is Next (roadmap).Credential: Inside the connector row ( credentials is write-only, AES-256-GCM at rest). | schema.list, table.describe, query.select (read); query.execute (write) is force-gated — a person approves every write, whatever the grants say. |
Remote agent (A2A)/v1/a2a/remote-agents | The remote agent card URL, fetched through an SSRF-guarded client; auth kinds none, api_key, bearer.Credential: Inside the remote-agent row (write-only). | ask (default) and delegate, granted like any other tool (source: a2a). |
HTTP API/v1/http-credentials | A credential (bearer, api_key or basic) that workflow http_request nodes present to your API. Used by workflows, not agents; no health probe — verified at call time.Credential: The HTTP credential itself (write-only). | None discovered — the workflow node names the request. An OpenAPI/REST import connector kind is Next (roadmap). |
A connection is credentials plus health
A connection is the record an administrator adds to make a connector usable: one labelled secret set (API key, token, or username and password), encrypted with AES-256-GCM at rest and write-only from then on — credentials never comes back from the API, is never logged, and is decrypted only inside the Tool Gateway at the moment of a call. For MCP servers a connection is its own resource (/v1/connections, optionally scoped to an org node); for database connectors and remote agents the credential is inside the row itself.
Every connection carries a health state. Today you check one explicitly: POST /v1/mcp-servers/:id/test connects through the gateway and lists tools, POST /v1/connectors/:id/test checks database connectivity. The vocabulary below is what the console badges say — persisted health with a background sweep and a Check now button is available in the console since the 2026-09-04 release.
Health states
| Badge | Code | Meaning |
|---|---|---|
| Connected | connected | Last check succeeded (handshake / tools listed / readiness passed). |
| Not checked yet | never_checked | Created; no check has run (also: tenant-owned stdio servers — "Manual check only"). |
| Needs credentials | needs_credentials | Auth is required but no credential is stored. |
| Credentials rejected | needs_reauth | Probe returned 401/403 or an expired token. The code name is kept; the wording is deliberate — there is no sign-in flow to send anyone through. |
| Broken | broken | Probe failed (network, TLS, 5xx, schema); last_error shows a redacted reason. |
| Disabled | disabled | Turned off by an admin (enabled=false / status≠active). |
| Awaiting first event | awaiting_first_event | Channels/webhook triggers only: configured, provider callback not yet received. |
| Last checked {ago} | stale | last_checked_at older than 3 × the sweep interval (default 45 min). Never shows plain green. |
| Checking… | checking | Transient while "Check now" runs. |
Precedence. When one badge summarises several connections (a connector card, or an agent’s connected systems), the worst state wins, in this order: disabled › needs_credentials › needs_reauth › broken › awaiting_first_event › connected › never_checked. Last checked … is an overlay on any state whose check is older than three sweep intervals — a connection is never shown plain green on stale data — and Checking… is a client-side transient while a check runs.
Tools and grants
A tool is one operation an agent may perform through a connector, validated against its schema and gated by the Tool Gateway.
Tools are what agents are allowed to do. Each connector exposes a list (an MCP server's tools/list, a database's read/write operations, a remote agent's ask/delegate). Agentic Workforce ME keeps the model's view small — only granted tools are offered per turn — because fewer visible tools mean more accurate agents. Every call passes one door: schema validation, the grant check, the approval check, the audited execution with credentials decrypted only at that moment.
Grants are default-deny for connector tools (MCP server, database, remote agent): a tool no grant mentions cannot be called, whatever the manifest says. Builtin tools the manifest lists in tools.builtin (for example kb.search) are the one exception — they run unless a grant explicitly denies them. Resolution for one concrete connector tool name works like this:
| Rule | What it means |
|---|---|
| Candidates | Every grant on the agent itself, on any org node in its chain (unit → section → department) or tenant-wide, whose tool_pattern matches the name. |
| Pattern specificity | exact (orders.refund) › glob (orders.*) › *. |
| Scope specificity | agent › unit › section › department › tenant — an agent-level rule beats an inherited one. |
| Decision | Order by scope, then pattern; the first match decides allow or deny. No match ⇒ deny for a connector tool, allow for a builtin the manifest lists. |
| Connection | The connection_id pinned on the winning grant, else the connection for that server at the nearest scope; none ⇒ the tool fails with NO_CONNECTION. |
| Effective tools | manifest allow-list ∩ grants. The manifest can only narrow, never widen; GET /v1/agents/:id/effective-config shows the resolved set with its bound connections — the fastest way to answer “what can this agent actually call?” |
| Listing by agent | GET /v1/tool-grants?agent_id= returns the agent’s effective grants — its own rows plus every tenant-wide row and every node-scoped row (agent_id null). Each row carries a derived scope (agent · node · tenant); deleting a tenant row from that response removes the grant for every agent, so filter on scope before any DELETE. |
Org-node inheritance is what makes a workforce manageable: grant crm.* to the Sales department once and every agent beneath it may use those tools, while a single agent-level deny still removes one of them for one agent. Fewer visible tools also mean more accurate agents — the model is offered only the tools its grants allow, per turn.
Approval policies vs manifest rules
Two mechanisms make a tool pause for a person, and both interrupt the run itself (a checkpointed interrupt() — nothing executes while the decision is pending). They differ in who owns them.
| Aspect | Manifest HITL rule | Approval policy |
|---|---|---|
| Who writes it | The agent builder, inside the agent manifest (hitl.rules[]); ships with the published version. | An administrator, in Integrations or via /v1/approval-policies; independent of any agent version. |
| Scope | One agent (plus node/tenant rule concatenation at resolve time). | One agent (agent_id) or the whole tenant; matched by tool_pattern and optional source. |
| What it decides | auto, require_approval or block per tool pattern, with approver role, SLA and timeout behaviour. | Risk tier, how many distinct approvers, approver role, SLA and escalation. |
| Default | hitl.default is review when omitted — every tool call pauses for approval unless a rule says auto. Set hitl.default: auto explicitly to let ungated tools run. | No policy ⇒ unchanged behaviour (the manifest rules apply). Database query.execute is force-gated regardless of either. |
Decisions come from the console’s Approvals page or from your own UI through the approvals API; the run resumes only through that decision path.
Connecting a system in five steps
The console’s Connect a system wizard (available in the console since the 2026-09-04 release) walks an administrator from a system to a governed agent in a handful of steps. The labels are the console’s own; the safe defaults are the point.
| Step | What you do | Safe by default |
|---|---|---|
| 1. Choose | Pick a connection kind — MCP server (API key, bearer or no auth), PostgreSQL / SQL Server / Oracle database, remote agent (A2A) — or one of your existing connectors. The catalog lists real connection kinds only (no demo or mock systems); vendor templates are Next. The name is derived from the endpoint host; transport and auth kind are prefilled. A Masar web source (any website, no API) is created from the Masar tab instead — paste a URL, confirm the suggested extractors — and is then attached exactly like the other kinds. | The catalog never prefills a local (stdio) transport. |
| 2. Connect & verify | One labelled secret field set (API key, token, or username + password). Connect stores the connection and runs the live handshake in the same call; the result is a health badge plus "N tools discovered". | Failures show a redacted, plain-language reason; the secret is never shown again. |
| 3. Choose tools | The discovered tools with descriptions and a risk hint from MCP annotations (read-only ● / write ▲); presets Read-only, All, None; a warning above 40 tools. | Nothing is preselected — default-deny. |
| 4. Grant & approve | Targets: active agents or an org node. Per tool, "Requires approval" — pre-set ON for write tools, OFF for read-only ones. Primary action Save to draft; Save and publish now only when every selected agent is active with no pending draft. | Nothing goes live until a person publishes. |
| 5. Done | A per-agent summary (draft version, what requires approval, published or the gate that blocked publishing) with Test in Playground, Add a trigger and View connected systems. | Every write is audited — connection.create, grant.create, approval_policy.create (or approval_policy.update when a disabled same-name policy is re-enabled), one summary row per attach (integration.attach) and an explicit agent.manifest.update row. |
API mapping
The vocabulary is new; the routes are not. Every path below exists today and keeps its technical name — the glossary renames labels, never paths. Every path takes an API key plus X-Tenant-Id. Creating, changing, deleting or testing anything, and GET /v1/agents/:id/effective-config, need the admin role (an API key acts as admin; a console session needs it explicitly); reads need member.
| Resource | Path | Notes |
|---|---|---|
| Connector · kind MCP server | /v1/mcp-servers | Register an MCP server (transport, endpoint, auth_kind); POST /v1/mcp-servers/:id/test lists its tools through the gateway. |
| Connection | /v1/connections | Encrypted credentials for an MCP server (credentials is write-only); node_id scopes it to an org node. |
| Connector · kind Database (database connectors) | /v1/connectors | Postgres, SQL Server or Oracle with credentials inside the row; POST /v1/connectors/:id/test checks connectivity. Path kept for compatibility — the noun is "database connector". |
| Connector · kind Remote agent (A2A) | /v1/a2a/remote-agents | A remote agent consumed as a tool (ask, delegate), with its own encrypted credentials. |
| Connector · kind HTTP API | /v1/http-credentials | Credential-only connector for workflow http_request nodes; used by workflows, not agents; no health probe. |
| Grant | /v1/tool-grants | Default-deny allow/deny rules per agent, org node or tenant-wide (scope: agent | node | tenant); optional connection_id pin. GET ?agent_id= returns the agent’s effective grants — its own plus the tenant-wide rows — so check scope before deleting. |
| Approval policy | /v1/approval-policies | Makes a tool pause for a named role before it runs; agent-scoped or tenant-wide. |
| Effective tools | /v1/agents/:id/effective-config | What one agent can actually call: manifest allow-list ∩ grants, with the bound connection. |
Request and response shapes are in the REST reference (Connectors, connections and tool grants) and on host an MCP server. Everything an agent does through a connector is recorded on the run — tool.called and tool.result steps, with arguments redacted per the schema — and every privileged mutation here (grant, policy, credential access) lands in the audit log, so Agentic Workforce ME can always answer who allowed what, and when.