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.
الموصّل هو الطريقة التي يصل بها Agentic Workforce ME إلى أحد أنظمتك: وسيلة النقل والمصادقة والأدوات التي يوفّرها.
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.
يصف الموصّل نظامًا خارجيًا يمكن لـ Agentic Workforce ME التصرّف فيه: خادم MCP أو قاعدة بيانات أو وكيل بعيد أو واجهة HTTP. هو تعريف وليس تسجيل دخول. لاستخدامه يضيف المشرف اتصالًا — بيانات اعتماد مشفّرة مع حالة صحّة حيّة — ويكتشف Agentic Workforce ME الأدوات التي يوفّرها النظام. لا يمكن استدعاء شيء قبل أن يسمح تصريح لوكيل أو وحدة تنظيمية محدّدة باستخدام أداة محدّدة، ويمكن وضع الأدوات الحساسة خلف سياسة موافقة ليقرّر شخص مسمّى قبل تنفيذ الاستدعاء.
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 خادم MCP /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) قاعدة بيانات (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) وكيل بعيد (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 واجهة HTTP /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 shipping in the next console release.
Health states
| Badge | Arabic | 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} | آخر فحص {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.
الأدوات هي ما يُسمح للوكلاء بفعله. يوفّر كل موصّل قائمة (قائمة tools/list لخادم MCP، عمليات القراءة/الكتابة لقاعدة بيانات، ask/delegate لوكيل بعيد). يُبقي Agentic Workforce ME ما يراه النموذج صغيرًا — تُعرض الأدوات المصرّح بها فقط في كل دور — لأن أدوات أقل تعني وكلاء أدقّ. يمرّ كل استدعاء من باب واحد: التحقق من المخطط، وفحص التصريح، وفحص الموافقة، والتنفيذ المسجّل مع فكّ تشفير بيانات الاعتماد في تلك اللحظة فقط.
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?” |
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 (shipping in the next console 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 starter-catalog card, an already-registered connector, or Custom MCP server / Database / Remote agent. The name is derived from the endpoint host; transport and auth kind are prefilled. | Templates never prefill 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 — today as connection.create, grant.create and approval_policy.create; the wizard adds one summary row (integration.attach) and an explicit agent.manifest.update row when it ships. |
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 or org node; optional connection_id pin. |
| 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.