API, CLI, and MCP
Connect authorized developer tools to Matte’s action API and discover their available capabilities.
Matte has a public API and a local CLI/MCP adapter for external tools. They use the same permission checks and action contracts as other supported clients. Start by discovering what your credential is allowed to do.
Before you connect
You need an authorized API credential and a workspace whose plan and policy allow API access. Personal credentials act within the issuing person’s current access. Service-account credentials use an explicitly granted workspace identity.
Developer credential setup and external-agent browser pairing are not currently exposed in the standard app navigation. This guide covers the interfaces available to existing authorized integrations. Confirm your credential and connection setup with your workspace administrator before continuing.
Built-in Matte agents use their own authenticated task and conversation flows. They do not require you to issue a browser API key. An external MCP client and a built-in workspace agent are separate ways of interacting with Matte.
Use a scoped credential
Credentials can grant record actions such as read, create, update, upsert, delete, and import for specific objects. Action grants can authorize individual stable action IDs on supported resources. Granting a key an action does not bypass the principal’s current permissions.
A key secret is displayed only when issued. Keep it in the tool host’s protected environment or a protected configuration file. Do not put it in a prompt, URL, source file, or command argument.
Revocation, expiration, changes to the person or service account, and plan restrictions affect subsequent requests. Disabling a service account removes its ability to act even if an old credential still exists.
Discover the supported actions
GET /api/v1/capabilities returns the currently authorized action catalog. GET /api/v1/capabilities/{actionId} returns the schema for one action. Use these responses to obtain action names, argument schemas, review policies, and supported resources.
The action catalog covers supported record operations and other domains, including object configuration, views, inventory, orders, counts, agendas, and chat. Actual availability depends on the installed apps, principal type, permissions, and execution policy.
POST /api/v1/actions/{actionId}/prepare prepares supported work for review. POST /api/v1/actions/{actionId}/execute executes through the ordinary server checks. Supply the schema’s arguments and current expected revisions where required.
Use the record and import APIs
The record API exposes object and field metadata, record listing, and batch create, update, upsert, and delete operations. Read metadata first so you use the object’s actual field keys and supported match fields.
Record batch calls accept at most 60 records. Inspect each row’s result: a batch can contain both successes and failures. The import-jobs API supports creating a job, appending batches, validating, committing, and canceling a job.
The public API applies a 100-request-per-minute limit and returns rate-limit headers. Honor Retry-After after a 429 response. Record API idempotency responses are retained for 24 hours; the same key with a different request is rejected as a conflict.
Run the local CLI
The repository includes the @matte/agent-tools package for Node 24 or later. Install and build it from the repository, then provide MATTE_BASE_URL and MATTE_API_KEY through your environment. The base URL is the app origin. HTTPS is required except for loopback development.
After building, run node packages/matte-agent-tools/dist/cli.js actions list to discover available actions. Run node packages/matte-agent-tools/dist/cli.js actions schema records.update to inspect the record-update schema. The CLI also prepares or executes actions, inspects operations, prepares supported inverse proposals, and creates, inspects, or cancels runs. Input files contain action arguments rather than the whole execution envelope.
The package is supplied in the Matte source repository; these commands do not assume a globally installed or publicly published npm package.
npm ci --prefix packages/matte-agent-tools
npm run build --prefix packages/matte-agent-tools
node packages/matte-agent-tools/dist/cli.js actions list
node packages/matte-agent-tools/dist/cli.js actions schema records.updateConnect an MCP host
The adapter is a local MCP server using stdio. Configure your host to launch Node with an absolute path to packages/matte-agent-tools/dist/mcp-main.js and supply the connection environment through the host’s secret configuration.
Alternatively, MATTE_CONFIG can point to an owner-only JSON file containing baseUrl and apiKey. The default location is ~/.config/matte/config.json. The file must belong to the current user, must not be a symlink, and must have no group or other permissions.
MCP exposes discovery, preparation, operation and run tools, plus a matte.action.ACTION_ID tool for each currently authorized action. It refreshes capabilities before execution and the server validates permission again. MCP mutations require an explicit idempotencyKey.
{
"command": "node",
"args": ["/absolute/path/to/inventorytracker/packages/matte-agent-tools/dist/mcp-main.js"]
}Handle review, conflicts, and partial results
Use a unique idempotency key for a logical mutation, and reuse it only for the same request. Keep the operation ID and response so you can check an uncertain outcome after a transport failure instead of blindly sending a new mutation.
An accepted, queued, or running response does not prove completion. Inspect operation status and any per-record failures. Re-read current records and revisions after a conflict before deciding how to proceed.
Preparing a proposal does not approve it. The adapter has no proposal-approval tool. Supported inverse proposals also require inspection and ordinary execution; they are not a universal undo command.
The CLI returns distinct exit codes for success, failure, invalid input, partial completion, and conflicts or required review. Automation should handle those outcomes separately rather than treating any JSON response as success.
Files and paired browser context
The CLI and MCP adapter support bounded attachment upload and download. For human chat, initialize an upload slot, transfer the file, complete the attachment, and then reference its ID in the message. Uploading a file alone does not send it. Downloads require a published message and current access.
An explicitly paired browser session can share page and selection context and accept the supported navigation.open, record.open, and records.select commands. Commands require current context revisions and an acknowledgement. Unsaved work or changed context can block them. Pairing setup is not currently available through standard app navigation.