Algenta MCP Server

Materialize a simulated repository decision in one of three modes. patch_only just returns the validated patch diff with applied=false and writes nothing. local_branch commits the patch to a new branch (default algenta/<plan-suffix>) in the engine-side checkout and returns commit_sha and local_checkout_path. remote_pr additionally pushes the branch and opens a pull request, returning pull_request_url. Both write modes are hard-gated: the simulation must satisfy policy thresholds (otherwise repository_apply_gate_failed) and write_permission=true must be passed explicitly (otherwise repository_write_permission_required). Use patch_only to review the diff before writing anything, and run_repository_fix to chain the whole flow. Requires decision_plan_id and simulation_id from simulate_repository.

Approve an agent run that is waiting on manual approval (status requires_approval) and execute it synchronously to completion. Runs in any other state fail with agent_run_invalid_state; an unknown run_id fails with agent_run_not_found. The approval is the human-in-the-loop gate for manual-mode runs and is audit-logged and checkpointed. Returns the updated run resource. Use resume_agent_run for paused runs instead.

Run multiple simulation requests in one call and return per-item success or failure details. Synchronous deterministic compute; nothing is persisted and no separate rate limit applies. Use simulate for a single request and submit_job for very large async runs. Returns total, succeeded, failed, and a per-item results array with index, success, the envelope's recommended_action and expected_value, or the item error.

Discover what one saved connector exposes — files, tables, endpoints, or items — with discovery labels and metadata for choosing what to onboard. The connector must be live: an untested or errored connector fails with not_connected, so run test_connector first. Use preview_browse_connector for an unsaved inline definition. Read-only against the source. Returns connector_type, items, total, message, labels, and discovery.

Cancel an agent run by run_id, ending its lifecycle at cancelled. Only a paused or requires_approval run can be cancelled — anything else fails with agent_run_invalid_state. Cancelling is idempotent: repeating the call on an already-cancelled or never-existing run_id returns success with already_absent: true instead of agent_run_not_found. Use resume_agent_run or approve_agent_run to continue a waiting run instead. The first cancellation is audit-logged and checkpointed; the run record is kept, not deleted, and repeats record nothing further. Returns the updated run resource.

Cancel a queued or running async simulation job by id. Use this for queued or running jobs; list_jobs shows their states. Cancelling is idempotent: repeating the call on an already-cancelled or never-existing id returns success with already_absent: true instead of an error; a completed or failed job is still refused with job_already_terminal. Returns the updated job record with its terminal status.

Run one ordered chat transcript through an Algenta model and return the assistant message plus token usage. The default text.tokenizer model is a deterministic tokenizer-backed utility route whose assistant message is a JSON tokenization summary of the user messages — not a generative LLM; provider-backed chat models advertised by list_models are routed through the configured provider service. Use responses for independent single-string utility calls. This tool does not stream and does not expose function/tool calling, and nothing is persisted. An unsupported model id fails with model_not_supported.

Run 2-10 named scenarios side by side and return the winner plus each scenario's deltas versus the best one. The winner is the scenario with the highest expected value; every entry reports its recommended_action, expected_value, probability_of_loss, and delta_vs_best. Each scenario's request uses the simulate payload shape; runs and seed are forwarded for reproducibility. Use recommend for a ranked recommendation over actions instead. Synchronous deterministic compute; nothing is persisted.

High-level data onboarding flow. Use this instead of advanced connector/source tools for normal users. Connect data once, pick the table/file/endpoint, and get a reusable dataset_id. If the result status is needs_selection, call connect_data again with connection_id and the chosen selection. Creating a connection persists it and the dataset under the active API key's organization, and live sources are dialed during this call; no separate per-route rate limit applies. Returns status with dataset_id and connection_id on success, or status needs_selection with the choices array to pick from.

Count how many tokens a supported deterministic Algenta tokenizer model produces for UTF-8 text (default text.tokenizer; call list_models for every supported model id). Use this for prompt-size checks and token budgeting; call tokenize when you also need the token strings. Read-only and deterministic: the same input and model always return the same count, and nothing is stored. Returns the resolved model id, its tokenizer_kind, and token_count. An unsupported model id fails with model_not_supported.

Create a persisted agent run lifecycle resource for a natural-language task. With approval_mode=auto (default) the run picks a tool from the task wording, executes synchronously, and returns completed; approval_mode=manual parks it at requires_approval until approve_agent_run, and start_paused=true parks it at paused until resume_agent_run. The run, its step log, append-only events, and a replayable checkpoint are persisted under the caller's organization and the creation is audit-logged. Use product_agent_run for the simpler synchronous helper, list_agent_runs to browse, and get_agent_run_events to follow the trail. Returns the full run resource with run_id and status.

Create a new API key for the current organization and return its raw_key value exactly once — it is never shown again, so store it immediately. expires_at optionally sets an ISO-8601 expiry and device_limit caps how many devices the key may register (validated against the plan ceiling, invalid_device_limit on excess). Key creation is rate-limited per organization (api_key_create_rate_limited). Use list_api_keys to see existing keys and revoke_api_key to retire one.

Create a Stripe Checkout session for the active organization and return its hosted checkout URL. The user completes the purchase in the browser; nothing is charged by this call itself. Requires an owner API key. plan defaults to developer; an unsupported plan fails with invalid_plan. Use get_billing_info to check the current plan and create_billing_portal to manage an existing subscription.

Create a Stripe Billing Portal session for the active organization and return its URL, where the user manages payment methods, invoices, and the subscription. Requires an owner API key and an existing billing account — an org that has never checked out fails with no_billing_account (call create_billing_checkout first). This call itself changes nothing.

Save one capability binding for a provider/profile pair and return it with its binding_id. scope (default workspace) decides who can use it, execution_owner decides where executions run (algenta_managed on the engine, client_managed in the customer app or adapter path), and config carries the profile's credentials and options. Find valid provider_id/profile_id pairs with list_capability_providers, then call discover_capability_binding to publish the binding's capabilities and test_capability_binding to verify. Persists the binding.

Save one connector configuration (host, credentials, options) for later data onboarding, health checks, and schema browsing. config is encrypted at rest and the new connector starts untested — call test_connector to verify it reaches the source, then browse_connector to discover what it exposes. Returns the saved connector with its connector_id, persisted under the active API key's organization. To try a definition without saving anything, call preview_test_connector instead.

Request a new isolated engine deployment for the active organization on the chosen provider and region. Returns immediately with status requested — provisioning is asynchronous, so poll get_deployment until status is active; API calls then route to the isolated deployment automatically. Requires an owner API key. Only one active or in-progress deployment is allowed per org (deployment_exists otherwise — call delete_deployment first), and unknown provider/region pairs fail validation; list_deployment_regions shows the valid combinations.

Create one stored, immutable repository DecisionPlan revision from a triage workspace evidence bundle and return its decision_plan_id plus the validated patch diff inline. snapshot_id is resolved from the bundle when omitted. This is the only LLM-touching stage of the repository chain; model optionally picks the planner model. The decision_plan_id feeds simulate_repository and apply_repository. Persists the plan revision. Use run_repository_pipeline to chain snapshot, triage, plan, and simulate in one call instead.

Create or reuse an immutable, content-hashed snapshot of a saved repository connector (a connector of a repository type — find its id with list_connectors). Re-running with identical inputs returns the existing snapshot (status='existing') instead of duplicating it. The snapshot is the input to triage_repository and query_repository_graph; every later stage references it by snapshot_id. Reads the repository and persists snapshot, symbol, and dependency graph artifacts; it never writes to the repository. Returns snapshot_id, resolved_revision, content_hash, file_count, language_counts, and artifact refs.

Delete one saved connector by id. Use update_connector to change config without losing the saved definition. Deleting is idempotent: repeating the call on an already-deleted or never-existing id returns success with already_absent: true instead of an error. Returns connector_id with deleted: true.

Delete one decision-memory record by id. Deletion is permanent; review with list_decisions first. Deleting is idempotent: repeating the call on an already-deleted or never-existing id returns success with already_absent: true instead of an error. Returns the deletion confirmation for the decision_id.

Request deprovisioning for one deployment by id. Deprovision with this before create_deployment when a deployment already exists. Deleting is idempotent: repeating the call on an already-deprovisioned or never-existing id returns success with already_absent: true instead of an error. Returns status 'deprovisioning' with the deployment_id; deprovisioning is asynchronous.

Delete one trigger by trigger_id (find ids with list_triggers). The trigger is removed immediately and will no longer fire automatically; its registration cannot be recovered from this tool. To stop a trigger temporarily instead, use pause_trigger. Deleting is idempotent: repeating the call on an already-deleted or never-existing id returns success with already_absent: true instead of an error. Returns trigger_id with deleted: true.

Disable one skill by deleting its capability binding (find binding ids with list_skills or list_capability_bindings). The skill immediately stops appearing in the capability catalog and can no longer be routed or executed; the deletion is permanent. Disabling is idempotent: repeating the call on an already-disabled or never-existing binding returns success with already_absent: true instead of an error. Returns binding_id with disabled: true. Use this only for permanent removal — re-enabling later requires a fresh enable_skill call.

Delete a saved dataset and disconnect it from future use. When no other dataset in the workspace still uses the backing saved connection, that connection is deleted too and connection_deleted is true in the response. Requires manage permission on the dataset (access_scope_denied otherwise). Use list_data to confirm the dataset first — deletion is immediate. Deleting is idempotent: repeating the call on an already-deleted or never-existing dataset_id returns success with already_absent: true instead of not_found. Returns dataset_id, status 'deleted', and connection_deleted.

Discover the capabilities one binding exposes and return them as catalog entries. Pass binding_id to discover a saved binding (this publishes or refreshes its capabilities in the catalog), or a full inline definition to preview-discover one that was never saved. Call this after create_capability_binding, then browse the result with list_capabilities.

Score the similarity between two caller-supplied embedding vectors with a supported deterministic metric (default embeddings.cosine_similarity). This tool does not generate embeddings from text — call embeddings first to produce the vectors. left and right must have equal length or the call fails with invalid_embedding_dimensions. Read-only and deterministic. Returns the resolved model id, similarity_metric, the score, and the shared vector dimension.

Generate one embedding vector per input string (a single string or a list of strings). The default text.hash_embedding_v1 model produces deterministic lexical hash embeddings — identical input always yields the identical vector; provider-backed embedding models advertised by list_models are routed through the configured provider service. Use embedding_similarity to score two vectors or rerank to order documents against a query vector. Read-only; nothing is stored. Returns one {index, embedding, token_count} item per input plus total token usage. An unsupported model id fails with model_not_supported.

Enable one prompt skill as a first-class capability binding and return its discovered catalog entry. The skill's instruction text becomes an instruction_only capability under the caller's user scope, selectable by route_capabilities. Persists a new binding; remove it with disable_skill. Use list_skills to see what is already enabled.

Execute one routed or known algenta_managed capability by capability id and return the execution receipt. client_managed routes must execute in the customer app or adapter path — this tool will not run them. If the capability requires approval (approval_required), this returns a pending plan (status='approval_required', plus plan_id/plan_hash/nonce) instead of executing — approval and the final plan_id execution are separate, credentialed HTTP operations and are NOT available as tools. Route first with route_capabilities when the right capability is not known.

Dispatch a logged decision to an external webhook and persist the execution receipt. Use record_outcome instead when reporting a result rather than dispatching an action. Returns the delivery receipt: decision_id, webhook_url, execution_status, response_code, executed_at, and the policy and schema snapshot ids.

Execute one local-runtime Mojo library function by module and function name. Pass args as either a JSON object, array, scalar, or null. This surface is local/runtime-backed only and does not route through hosted data/query APIs.

Manually fire a trigger — evaluates its condition and runs the simulation template regardless of whether the threshold is currently met. Useful for testing triggers or forcing an immediate evaluation. Use pause_trigger to stop automatic firing without deleting the trigger. Returns trigger_id, condition_met, fired, simulation_run_id, recommended_action, expected_value, confidence, and fired_at.

Fetch one persisted agent run by run_id: status, task, selected_tool, steps, result, tools_used, and the policy/schema snapshot ids it ran under. Use list_agent_runs to find run ids, get_agent_run_events for its event trail, and get_agent_run_checkpoints for replay checkpoints. Read-only; an unknown run_id fails with agent_run_not_found.

List the persisted checkpoints of one agent run — the deterministic snapshots written at creation and every lifecycle transition that make the run replayable. Use query_agent_run_checkpoints to search checkpoints across runs. Read-only; an unknown run_id fails with agent_run_not_found. Returns the run's checkpoint records.

Fetch the append-only event stream of one agent run — run_created, tool_selected, tool_executed, run_completed, and the pause/approve/cancel transitions — in order. Use get_agent_run_mission_events for the canonical mission-event projection of the same trail. Read-only; an unknown run_id fails with agent_run_not_found. Returns data plus total_events.

Fetch the canonical mission-event records of one agent run — the typed, indexed projection of its lifecycle used for audit and replay. Use get_agent_run_events for the raw append-only stream and query_agent_run_mission_events to search mission events across runs. Read-only; an unknown run_id fails with agent_run_not_found. Returns the run's canonical mission-event records.

Fetch the runtime telemetry batches recorded for one agent run — the module-level timing and execution detail captured while it ran. Use query_agent_run_telemetry to search telemetry across runs by kind or module. Read-only; an unknown run_id fails with agent_run_not_found. Returns the run's telemetry batches.

Get aggregate usage analytics over the organization's simulation runs inside a lookback window: total_simulations, avg_confidence, action_breakdown (how recommended actions distribute), and latency_p95_ms. days sets the window (default 30, range 1-365). Use list_runs for individual runs instead of aggregates. Read-only.

Query the organization's immutable Parquet audit-log artifacts with pagination (defaults page 1, limit 25) and exact-match filters, including content_hash for pinpointing one artifact. Artifacts are the tamper-evident copy of the audit trail; use get_audit_logs for the live audit-event table. Requires an admin API key; a workspace-scoped key sees only its own workspace's artifacts. Read-only. Returns entries plus total, page, limit, and pages.

Query the organization's audit-event log, newest first, with pagination (defaults page 1, limit 25) and exact-match filters. Every entry records who did what to which resource with which result; an org with no events returns an honest empty page. Requires an admin API key. Use get_audit_log_artifacts for the immutable Parquet artifact copy, and filter by policy_snapshot_id, schema_snapshot_id, manifest_version, or request_hash to trace one execution. Read-only. Returns entries plus total, page, limit, and pages.

Get current billing plan and subscription info for the active organization. Read-only and non-destructive; not separately rate-limited. Use create_billing_checkout or create_billing_portal to change anything. Returns plan, stripe_customer_id, subscription_status, and current_period_end.

Fetch one unified capability catalog entry by capability_id: kind, provider, binding, execution owner, approval requirement, and tags. include_instruction=true also returns the skill instruction text. Find capability ids with list_capabilities or route_capabilities. Read-only; an unknown id fails with not_found.

Fetch one saved connector by connector_id: name, connector_type, status, visibility, timestamps, and the config fingerprint — never the stored credentials. Use list_connectors to find ids. Read-only; an unknown or invisible id fails with not_found.

Get the machine-readable Algenta public contract. Use this when an agent needs the canonical discovery, summary, query, batch, SQL report, governed filter rules, CLI, or MCP entrypoints before planning tool use. Read-only and non-destructive; not separately rate-limited.

Get a saved dataset plus its schema and relationship metadata by dataset_id. Read-only and non-destructive; reads only the active API key's organization and is not separately rate-limited. Use get_data_summary first for a low-token look. Returns the dataset record and its schema: row_count, columns, roles_summary, formulas, and query_hints.

Get the low-token dataset selection summary for a saved dataset_id. Use this after list_data(search=..., compact=true) before paying for the full schema payload. Read-only and non-destructive; reads only the active API key's organization and is not separately rate-limited. Returns dataset_id, name, status, source_names, row_count, column_count, registered_at, and query_hints.

Get the live training status and model tier of one dataset: whether semantic training is still running or the dataset is ready, and which model serves queries — model_tier 'none' = deterministic fallback only, 'base' = generic model, 'schema' = fully trained schema-specific model (best quality). Poll this after onboard_dataset until training completes, and use retrain_dataset after schema or alias changes. Read-only; an unknown dataset_id fails with not_found. Also returns name, column_count, source_names, and updated_at.

Fetch one decision-memory record by id. Read-only and non-destructive; not separately rate-limited. Use list_decisions to find decision ids. Returns the full decision record including context, options_considered, risk fields, integrity hashes, and outcome fields when recorded.

Fetch the current deployment for the active organization, if one exists. Read-only and non-destructive; not separately rate-limited. Poll this after create_deployment until status is active. Returns the deployment record (deployment_id, provider, region, status, config, created_at) or null when the organization is on the shared pool.