Register capability providers & bindings
Register capability providers, create and test bindings, discover and authorize capabilities, and enable skills — the setup layer behind the Algenta capability plane.
A binding is the connective tissue of the capability plane: it wires one provider profile (an MCP server, a skill pack, a data connector, a native tool pack, a runtime library) to your organization, holds the encrypted config, and produces the capabilities you can route and execute. This guide covers the setup layer — list providers, create a binding, test and discover its capabilities, authorize it, enable skills, and find external MCP providers. Once a binding is ready, use Route and execute capabilities to run its capabilities.
You need an API key (see Authentication) exported as $ALGENTA_API_KEY, and a running engine — the hosted API at https://api.algenta.ai or a self-hosted server at http://localhost:8000. Every route below lives under /v1/capability-providers, /v1/capability-bindings, and /v1/capabilities.
Before you start
A provider groups one or more profiles by type. provider_type is one of:
provider_type
What it is
data_connector
A connected data source (database, warehouse, REST API).
mcp_provider
An external Model Context Protocol server.
skill_pack
Prompt-skills enabled as first-class capabilities.
native_tool_pack
Built-in engine tools.
runtime_library_pack
Runtime-library operations.
A binding is created at one scope — user, workspace (default), or organization — which controls who can see and route to its capabilities.
The binding lifecycle
List the providers available to your org
GET /v1/capability-providers returns every provider visible to your org, each with its provider_type, active flag, supported_execution_owners, and the profiles you can bind against. Note the provider_id and a profile_id you want to use.
curl -sS "https://api.algenta.ai/v1/capability-providers" \
-H "Authorization: Bearer $ALGENTA_API_KEY"import os
from decision_engine import AlgentaClient
client = AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"])
for provider in client.list_capability_providers():
print(provider.provider_id, provider.provider_type, provider.active)import { AlgentaClient } from "algenta-sdk";
const client = new AlgentaClient({ apiKey: process.env.ALGENTA_API_KEY });
const providers = await client.listCapabilityProviders();
for (const p of providers) {
console.log(p.provider_id, p.provider_type, p.active);
}Create a binding
POST /v1/capability-bindings binds a provider_id + profile_id pair to your org. binding_name is required; scope defaults to workspace; execution_owner, scope_ref, config, and customer_metadata are optional. Any credential in config is encrypted at rest and never returned. The example wires a generic external MCP server (see Connect an external MCP server for MCP-specific config).
curl -sS -X POST "https://api.algenta.ai/v1/capability-bindings" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider_id": "provider.mcp.generic",
"profile_id": "profile.mcp.workspace",
"binding_name": "Acme tools",
"scope": "workspace",
"execution_owner": "algenta_managed",
"config": {
"server_url": "https://mcp.acme.internal/mcp",
"auth": {"type": "bearer", "token": "'"$ACME_MCP_TOKEN"'"}
}
}'import os, requests
resp = requests.post(
"https://api.algenta.ai/v1/capability-bindings",
headers={"Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"},
json={
"provider_id": "provider.mcp.generic",
"profile_id": "profile.mcp.workspace",
"binding_name": "Acme tools",
"scope": "workspace",
"execution_owner": "algenta_managed",
"config": {
"server_url": "https://mcp.acme.internal/mcp",
"auth": {"type": "bearer", "token": os.environ["ACME_MCP_TOKEN"]},
},
},
)
binding = resp.json()
print(binding["binding_id"], binding["status"])The 201 response carries the binding_id, its status, execution_owner, and scope_ref. Export the id as $BINDING_ID for the next steps.
Test the binding
POST /v1/capability-bindings/{binding_id}/test verifies connectivity for a saved binding. To validate config before saving, POST /v1/capability-bindings/test with the same body you would pass to create (a preview test).
curl -sS -X POST "https://api.algenta.ai/v1/capability-bindings/$BINDING_ID/test" \
-H "Authorization: Bearer $ALGENTA_API_KEY"import os, requests
resp = requests.post(
f"https://api.algenta.ai/v1/capability-bindings/{os.environ['BINDING_ID']}/test",
headers={"Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"},
)
result = resp.json()
print(result["success"], result["binding_status"], result.get("latency_ms"))const result = await client.testCapabilityBinding(process.env.BINDING_ID!);
console.log(result.success, result.binding_status, result.latency_ms);The result reports success, the resulting binding_status, a message, an optional latency_ms, and a details object.
Discover its capabilities
POST /v1/capability-bindings/{binding_id}/discover connects to the provider, enumerates what it offers, and writes each item into the unified catalog. A preview form (POST /v1/capability-bindings/discover) discovers against an unsaved binding config.
curl -sS -X POST "https://api.algenta.ai/v1/capability-bindings/$BINDING_ID/discover" \
-H "Authorization: Bearer $ALGENTA_API_KEY"import os, requests
resp = requests.post(
f"https://api.algenta.ai/v1/capability-bindings/{os.environ['BINDING_ID']}/discover",
headers={"Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"},
)
data = resp.json()
print(data["capability_count"], data["binding_status"])
for cap in data["capabilities"]:
print(cap["capability_id"], cap["kind"], cap["name"])const data = await client.discoverCapabilityBinding(process.env.BINDING_ID!);
console.log(data.capability_count, data.binding_status);
for (const cap of data.capabilities) {
console.log(cap.capability_id, cap.kind, cap.name);
}The response returns capability_count, a manifest_hash, discovered_at, and a capabilities[] array of catalog entries (capability_id, kind, name, execution_owner, approval_required, binding_status, …). Each kind is one of dataset, mcp_tool, mcp_resource, mcp_prompt, skill, native_tool, or runtime_library.
Authorize an OAuth-style binding
Providers that require a delegated grant move to status: "authorizing" until you complete an authorization handshake. Start it, send the user to the returned authorize_url, then complete it with the callback.
The start response carries session_id, authorize_url, expires_at, and requested_scopes. The complete response returns the final status and, on success, authorized_at. In the SDK these are startCapabilityAuthorization(bindingId, request) and completeCapabilityAuthorization(request).
Manage bindings
GET /v1/capability-bindings lists your bindings and accepts optional provider_id and scope filters. GET, PATCH, and DELETE on /{binding_id} read, update, and remove one.
Enable and disable skills
A skill is a prompt-instruction registered as a first-class capability. List the skills your org has with GET /v1/capabilities?kinds=skill. Enabling a skill creates a skill_pack binding and discovers it in one motion; disabling it deletes that binding.
List external MCP providers
External MCP servers appear in the provider list with provider_type: "mcp_provider". Fetch GET /v1/capability-providers and filter for that type; the TypeScript SDK exposes listMcpProviders() as a convenience.
Route and execute what you bound
Once a binding is ready and its capabilities are discovered, hand the engine an objective and let it pick and run one: POST /v1/capabilities/route returns a plan and POST /v1/capabilities/execute runs it. The full flow — with fallbacks, approval gates, and execution ownership — is covered in Route and execute capabilities.
Troubleshooting
Next steps
Last updated
Was this helpful?