API and MCP

Address and authorization

Service address: https://api.extella.ai. The requests below use the POST method with a JSON body.

Get a token in your Extella account. You can ask the agent: “Create an API token for my script”. Use the IDs of the agent and profile in whose scope you save programs. Do not publish the token and do not put it in the code of a website page.

Content-Type: application/json
X-Auth-Token: YOUR_TOKEN
X-Profile-Id: YOUR_PROFILE_ID
X-Agent-Id: YOUR_AGENT_ID

Keep the token on a server or in your local environment. The Python example asks for it with hidden input.

POST/api/expert/save

Creates or replaces a saved program. name, description and code are required. Set cspl explicitly.

{
  "name": "add_two_numbers_v1",
  "description": "Add two numbers a and b; return total.",
  "code": "def add_two_numbers_v1(a: float = 0, b: float = 0) -> dict:\n    return {\"total\": a + b}",
  "cspl": "fython",
  "kwargs": {},
  "global": false
}

Check the name first. Saving over an existing record replaces its code.

POST/api/expert/get

Returns the record by name. Check the fields expert_name, expert_code, cspl and expert_params.

{"name": "add_two_numbers_v1"}

POST/api/expert/run

Passes parameters to a saved program. In the current request schema, the name goes in the expert_name field.

{
  "expert_name": "add_two_numbers_v1",
  "params": {"a": 5, "b": 7},
  "targets": ["DEVICE_ID"],
  "wait": true
}

Check status, then the contents of result. On an error, read execution_log. HTTP 200 alone does not prove that the program finished successfully.

Deferred result

If the call returned a task_id, request its state with POST /api/tasks/check and the body {"task_id":"TASK_ID"}. Wait for a final status before you repeat an action that changes data.

Limit the number of retries and the total waiting time. Do not print the token to a log while you investigate an error.

Troubleshooting

Connecting through MCP

MCP gives an agent access to Extella tools. In a client that supports Streamable HTTP and authorization headers, add a connection:

After connecting, get the list of available tools. First find and read the program you need. The tested examples run it with the run_expert tool; take the parameters from the schema your MCP server returned.

Give the agent only the rights it needs. Connecting tools does not replace preparing the device.