General API

Build agents and integrations for your Tensorworks organization. Work with projects, Kanban boards and sprints, chat and direct messages, encrypted files, calendars, websites, domains and DNS, and phone numbers.

The API is a Model Context Protocol server. Use any MCP client, or send JSON-RPC requests over HTTPS with fetch or curl. Authenticate with OAuth 2.1 (authorization code with PKCE and dynamic client registration) or with an agent link from an organization admin.

Endpoint

https://tensorworks.net/mcp

Protocol
MCP over Streamable HTTP, JSON responses
Auth
OAuth 2.1 bearer token, scope workspace
Discovery
/.well-known/oauth-protected-resource/mcp
Tools
116

Getting started

Quickstart

MCP clients that support OAuth need only the endpoint URL. The client discovers the authorization server, registers itself and opens a browser for sign-in.

  1. Add the server. Run your client’s command, or add the URL to its mcpServers configuration.
  2. Sign in. In Claude Code, run /mcp and select tensorworks. Codex opens the browser automatically. If it doesn’t, run codex mcp login tensorworks. Sign in, confirm the agent name and callback, and select Allow access.
  3. Call a tool. The agent joins your organization’s team under Chat. It has your access until an admin limits it. Ask it to list your projects.

For a custom client, see Authentication and Making requests.

Terminal
codex mcp add tensorworks --url 'https://tensorworks.net/mcp'

Getting started

Conventions

  • Most ids are 32 lowercase hex characters. A domain’s id is its name (example.com), a DNS record’s id is <domain>/<id>, and a phone number’s id is the number in E.164 format (+19195550142).
  • A file’s id is the SHA-256 of its contents (64 hex characters). Key ids are 16 hex characters, and nonces are 24.
  • A space is a resource in a project: a board, chatroom, document repository, calendar, website, domains resource or phone numbers resource. Its kind identifies the resource type. See Resources.
  • Timestamps are ISO 8601 UTC. pinned is 0 or 1. A project’s resources and subprojects are sorted with pinned items first, then by position. archived_at and archived_by (the account that archived it) are null unless the item is archived.
  • Every tool returns a single text item containing JSON. Parse content[0].text.
  • Amounts are in whole US cents. Tools that charge (domains, phone numbers) require the quoted price_cents and fail if the price has changed.
  • Text inputs are trimmed before length checks.
  • To mention someone in a message, description or comment, write @handle in the text and pass their id in mentions (both from list_people). Mentioned people are notified, even if the agent acts on their behalf. @channel mentions everyone with access to the room.

Getting started

Enterprise API

Enterprise organizations also have the Enterprise API, an HTTP API for compliance and security tools, separate from MCP. It authenticates with tokens an admin makes in Manage org › API and answers plain JSON.

Authentication

Authentication

Tensorworks is the OAuth 2.1 authorization server for its MCP endpoint, as described in the MCP authorization specification. A client registers, the user approves it, and the client exchanges the authorization code for tokens.

An approved client joins the selected organization’s team as an agent acting on the user’s behalf. The agent has the user’s access until an admin limits it. Removing or disconnecting the agent revokes its tokens immediately.

EndpointPurpose
GET /.well-known/oauth-protected-resource/mcpResource metadata
GET /.well-known/oauth-authorization-serverAuthorization server metadata
POST /registerDynamic client registration
GET /authorizeStart sign-in and consent in the browser
POST /tokenExchange a code or refresh token
POST /revokeRevoke a token and its grant
Without a token
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://tensorworks.net/.well-known/oauth-protected-resource/mcp", scope="workspace"

Authentication required

Authentication

Discovery

A request without a valid token returns 401 with a WWW-Authenticate header pointing to the resource metadata. Resource metadata identifies the authorization server. That server’s metadata lists its endpoints. Use discovery rather than hard-coded endpoints.

The server supports the S256 code challenge method, the authorization_code and refresh_token grants, and the workspace scope. Password grants are not supported.

Request
curl https://tensorworks.net/.well-known/oauth-protected-resource/mcp

curl https://tensorworks.net/.well-known/oauth-authorization-server
Protected resource
{
  "resource": "https://tensorworks.net/mcp",
  "authorization_servers": [
    "https://tensorworks.net/"
  ],
  "scopes_supported": [
    "workspace"
  ],
  "resource_name": "Tensorworks"
}
Authorization server
{
  "issuer": "https://tensorworks.net/",
  "authorization_endpoint": "https://tensorworks.net/authorize",
  "response_types_supported": [
    "code"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint": "https://tensorworks.net/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "none"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "scopes_supported": [
    "workspace"
  ],
  "revocation_endpoint": "https://tensorworks.net/revoke",
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_post"
  ],
  "registration_endpoint": "https://tensorworks.net/register"
}

Authentication

Register a client

Register once and store the client_id. Registrations do not expire.

Body

redirect_uris string[] Required
Callback URIs using HTTPS, or HTTP on 127.0.0.1, localhost or [::1]. Fragments and credentials are not allowed.
client_name string
Client name, shown on the consent page and used as the agent’s name.
token_endpoint_auth_method string
none for public clients (CLI, desktop), or client_secret_post to receive a client_secret for token requests.
grant_types string[]
authorization_code and refresh_token.
response_types string[]
code.
POST /register
curl https://tensorworks.net/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Release bot",
    "redirect_uris": ["http://127.0.0.1:8976/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"]
  }'
201 Created
{
  "redirect_uris": [
    "http://127.0.0.1:8976/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "client_name": "Release bot",
  "client_id": "95199f21-8b87-4da0-8d2e-d886d34cf24a",
  "client_id_issued_at": 1790811964
}

Authentication

Authorize

Open /authorize in the user’s browser with a PKCE challenge. The user signs in if needed and reviews the client name, callback and organization. Users who belong to several organizations choose one. The user then approves or denies access. Allow access redirects to redirect_uri with code, state and iss. Deny redirects with error=access_denied.

Query

response_type string Required
code.
client_id string Required
From registration.
redirect_uri string Required
One of the registered URIs.
code_challenge string Required
Base64url SHA-256 of the code verifier (43 characters).
code_challenge_method string Required
S256.
resource string Required
The MCP endpoint, exactly https://tensorworks.net/mcp. Tokens are bound to it.
scope string
workspace (the only scope).
state string
Returned unchanged in the redirect. Verify that it matches the value you sent.

Authorization requests expire after 10 minutes, and codes after 5 minutes. Verify that iss is https://tensorworks.net/ before using the code.

Build the URL
import { createHash, randomBytes } from 'node:crypto';

const verifier = randomBytes(32).toString('base64url');
const state = randomBytes(16).toString('base64url');
const url = new URL('https://tensorworks.net/authorize');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id: client.client_id,
  redirect_uri: 'http://127.0.0.1:8976/callback',
  code_challenge: createHash('sha256').update(verifier).digest('base64url'),
  code_challenge_method: 'S256',
  scope: 'workspace',
  state,
  resource: 'https://tensorworks.net/mcp'
}).toString();
// open url in the user's browser, then wait for the redirect to your callback
Redirect after Allow access
http://127.0.0.1:8976/callback
  ?state=zsek4YZvGZ4VKMSTi5ifqQ
  &iss=https%3A%2F%2Ftensorworks.net%2F
  &code=5761e31cd8538b7da8a3ddd4157bd6327f0c…

Authentication

Exchange the code

Send the code and verifier as a form-encoded POST to /token. Codes are single-use.

Body

grant_type string Required
authorization_code.
code string Required
From the redirect.
code_verifier string Required
The verifier used to generate the challenge.
client_id string Required
From registration.
redirect_uri string Required
Same as in the authorization request.
resource string Required
The MCP endpoint.
client_secret string
Only for client_secret_post clients.

Send the access token as Authorization: Bearer <access_token>. It expires after one hour.

POST /token
curl https://tensorworks.net/token \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d code_verifier=$VERIFIER \
  -d client_id=$CLIENT_ID \
  -d redirect_uri=http://127.0.0.1:8976/callback \
  -d resource=https://tensorworks.net/mcp
200 OK
{
  "access_token": "5761e31cd8538b7da8a3ddd4157bd632e2bd9c9d416547ed5d7a11875077c2f74bca636535338bc83ff8611e8bbe126d",
  "refresh_token": "5761e31cd8538b7da8a3ddd4157bd63233ecec8a337b80963ad082fcaab088b85367e1ab4b96d82e8a6b643c20a8e8c9",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "workspace"
}

Authentication

Refresh tokens

Refresh tokens expire after 30 days and rotate on every use. Each refresh returns a new token pair and invalidates the previous refresh token. The server treats reuse of an invalidated refresh token as token theft. It revokes the grant and removes the agent from the team. The user must approve the client again.

Body

grant_type string Required
refresh_token.
refresh_token string Required
The latest refresh token.
client_id string Required
The client id the token was issued to.
resource string Required
The MCP endpoint.
POST /token
curl https://tensorworks.net/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID \
  -d resource=https://tensorworks.net/mcp
400 Bad Request · a spent token
{
  "error": "invalid_grant",
  "error_description": "Refresh token reuse detected; sign in again."
}

Authentication

Revoke access

Revoking any access or refresh token ends its grant. All tokens for the connection stop working, and the agent is removed from the team. Removing the agent under Chat has the same effect. Signing out of the browser does not affect agents.

POST /revoke
curl https://tensorworks.net/revoke \
  -d token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID
200 OK
{}

Requests

Making requests

Send each call as an HTTP POST containing one JSON-RPC 2.0 message to https://tensorworks.net/mcp. The endpoint is stateless and responds with JSON. MCP clients send initialize and tools/list first, but tools/call also works on its own. There is no event stream. GET and DELETE return 405.

Headers

Authorization string Required
Bearer <access_token>. Omit for agent links.
Content-Type string Required
application/json.
Accept string Required
application/json, text/event-stream (required by Streamable HTTP).
MCP-Protocol-Version string
The negotiated protocol version. MCP clients send it after initialize.

Tool examples use the callTool helper shown here to unwrap results and throw on errors.

initialize
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "release-bot", "version": "1.0.0" }
    }
  }'
Response
{
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "tensorworks",
      "version": "1.0.0"
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}
callTool.js
const MCP_URL = 'https://tensorworks.net/mcp';
let nextId = 1;

// calls one tool and returns its parsed result
export async function callTool(name, args = {}) {
  const response = await fetch(MCP_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TENSORWORKS_TOKEN}`,
      'Content-Type': 'application/json',
      Accept: 'application/json, text/event-stream'
    },
    body: JSON.stringify({ jsonrpc: '2.0', id: nextId++, method: 'tools/call', params: { name, arguments: args } })
  });
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  const { result, error } = await response.json();
  if (error) throw new Error(error.message);
  if (result.isError) throw new Error(result.content[0].text);
  return JSON.parse(result.content[0].text);
}
A tool result
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"organization\":\"a3f1c9e07b5d4e2f8c6a1b0d9e8f7c6b\",\"email\":\"you@example.com\",\"id\":\"5761e31cd8538b7da8a3ddd4157bd632\",\"access\":\"full\"}"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": 1
}

Requests

Toolsets

Every tool belongs to one toolset, named by the prefix of its name (board_get is in board). The core tools, whoami, list_projects, list_spaces, list_people and set_status, have no prefix and are always served.

ToolsetTools for
projectCreating, renaming and archiving projects and resources.
chatChatroom messages.
dmThe agent’s direct messages.
boardBoards, cards, card fields and sprints.
fileFiles and folders in document repositories, card attachments, chatroom files and website assets, and file transfers.
calendarCalendars and events.
websiteWebsite templates and publishing.
domainDomains, DNS records, contacts and certificates.
phonePhone numbers, calls, voicemail and texts.

To serve only some toolsets, add ?toolsets= with a comma-separated list to the MCP URL, for example https://tensorworks.net/mcp?toolsets=board,file. The core tools are always included, and calling a tool outside the chosen toolsets fails as an unknown tool. An unknown toolset name returns 400.

A limited agent is shown only the toolsets of the resources it can open, and never project. If it can only read every resource of a kind, it is shown only the tools that read them. This affects only tools/list: a tool it isn’t shown still answers, with the permission error it would give anyway.

Each tool carries MCP annotations that clients can use to decide when to ask before calling it. readOnlyHint marks tools that only read. destructiveHint marks tools that delete, unlock a domain, spend money that isn’t refunded, or replace what the public is served. idempotentHint marks tools that change nothing more when called again. openWorldHint marks tools that reach a registrar, certificate authority, DNS, carrier or the web.

Requests

Errors

Request errors return an HTTP error status. Tool failures return HTTP 200 with isError: true and a text explanation. OAuth endpoints return standard error and error_description fields.

StatusMeaning
200 isErrorTool call refused: invalid arguments (MCP error -32602), not found, or missing permission.
400An unknown name in ?toolsets=. OAuth: invalid_request, invalid_grant (expired, used or revoked), invalid_scope, invalid_client_metadata.
401Access token missing, expired or revoked. Refresh or authorize again.
403Invalid host: the request used a host name other than the server’s.
404The agent link is invalid, or its agent was removed.
405GET or DELETE on the MCP endpoint.

Anything the agent can’t access returns a not-found error, whether or not it exists.

A refused tool call
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "You cannot create cards in Done."
      }
    ],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 7
}
Invalid arguments
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "MCP error -32602: Input validation error: Invalid arguments for tool project_create: Too small: expected string to have >=1 characters at name"
      }
    ],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 8
}
An OAuth error
{
  "error": "invalid_grant",
  "error_description": "Grant expired or revoked."
}

Requests

Access and permissions

New agents have full access. An agent acts as the person who connected it (or as the organization, for agent links) in every project, and can spend money wherever that person can (domains, certificates, phone numbers). An admin can limit an agent to specific roles and grants from the agent’s page under Chat. A limited agent:

  • Sees only the projects and resources it is granted. Everything else returns not found.
  • Can’t create, rename or archive projects or resources (This agent may not change projects.).
  • Is shown only the toolsets of the resources it can open, and only the reading tools of those it can only read.
  • Has full access, read-only access or selected permissions on each granted resource, which list_spaces reports as null, [] or a list of permissions.

The server checks these permissions on every write, and a refused write names the missing permission. See the permissions for boards, chatrooms, document repositories, calendars, websites, domains and phone numbers.

Requests

Limits

WhatLimit
Access token1 hour
Refresh token30 days, rotated on every use
Authorization request / code10 minutes / 5 minutes, single use
Project and resource names1–200 characters
Mentions50 people per text
File sizeThe organization's maximum file size, 5 GiB unless its owner chose otherwise (from 10 MiB to 50 GiB), uploaded in 8 MiB parts
Upload URLs / download URLs1 hour / 5 minutes

Each resource page lists its own limits.

File transfers

Envelope format

Clients encrypt each file into a protobuf CompressedEnvelope before uploading it. File bytes never pass through the API. Tools return presigned URLs, and clients PUT and GET envelopes directly. Files are stored as pieces of up to 1 MiB under a Merkle tree. Each piece has its own envelope, named by its SHA-256, so you can read any range independently. An upload sends the whole file as one envelope, which the server verifies and then stores as pieces.

Uploads are encrypted with AES-256-GCM using the upload plan’s key and nonce, without compression. The additional authenticated data (AAD) binds these header fields:

BytesAAD field
0Version, 0x01
1Codec, 0 for none
2–9Plaintext size, unsigned 64-bit big-endian
10Encryption, 1 for AES-256-GCM
11Key id length
12…Key id bytes

To stream large files, write the header fields before the payload, as in the example. The server checks the size, tag and plaintext hash before listing the file. Downloaded pieces may be gzipped (codec 3). Decompress them after decrypting.

compressed.proto
message CompressedEnvelope {
  int64 uncompressed_size = 1;  // plaintext bytes
  Codec codec = 2;              // 0 none (uploads), 3 gzip
  bytes payload = 3;            // ciphertext followed by the 16-byte GCM tag
  Encryption encryption = 5;    // 1 AES-256-GCM
  bytes nonce = 6;              // 12 bytes
  bytes key_id = 7;             // 8 bytes; hex in the API
}
seal.js
import { createCipheriv } from 'node:crypto';

const varint = (n) => {
  const out = [];
  do { out.push((n % 128) | (n >= 128 ? 128 : 0)); n = Math.floor(n / 128); } while (n);
  return Buffer.from(out);
};

// seals plaintext as the CompressedEnvelope an upload plan expects
export function seal(plaintext, key, keyId, nonce) {
  const aad = Buffer.alloc(12);
  aad[0] = 1;                                   // aad version
  aad[1] = 0;                                   // codec: none
  aad.writeBigUInt64BE(BigInt(plaintext.length), 2);
  aad[10] = 1;                                  // encryption: AES-256-GCM
  aad[11] = keyId.length;
  const cipher = createCipheriv('aes-256-gcm', key, nonce);
  cipher.setAAD(Buffer.concat([aad, keyId]));
  const payload = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
  return Buffer.concat([
    Buffer.from([0x08]), varint(plaintext.length), // 1 uncompressed_size
    Buffer.from([0x28, 0x01]),                    // 5 encryption
    Buffer.from([0x32, nonce.length]), nonce,     // 6 nonce
    Buffer.from([0x3a, keyId.length]), keyId,     // 7 key_id
    Buffer.from([0x1a]), varint(payload.length),  // 3 payload: ciphertext + tag
    payload
  ]);
}

File transfers

Upload a file

  1. Hash the file with SHA-256 and call file_begin_upload with its name, hash and size. If the content already exists, it returns { "complete": true } and the upload is done.
  2. Fetch the key named by the plan’s keyId with file_get_key.
  3. Encrypt the file into one envelope and split it into 8 MiB parts. The last part may be shorter.
  4. PUT each part to its URL, in order, with its exact Content-Length. Save the ETag from each response.
  5. Call file_complete_upload with the ticket and parts. To cancel, call file_abort_upload.
  • Folder: pass folder_id (from file_list_folders).
  • Card attachment: pass the board as space_id and the card as card_id to file_begin_upload and file_complete_upload.
  • Chatroom: pass the room as space_id. When the upload completes, the file is posted as a message (Shared <name>) with the file as its attachment.
upload.js
import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';

const bytes = await readFile('spec.md');
const hash = createHash('sha256').update(bytes).digest('hex');
const where = { project_id: 'b6909c9cf00c1d482686b5f52eadd58e', space_id: '88befbbdf3a1551c4567223ba4d11f90' };

const plan = await callTool('file_begin_upload', { ...where, name: 'spec.md', hash, size: bytes.length });
if (!plan.complete) {
  const { key } = await callTool('file_get_key', { ...where, key_id: plan.keyId });
  const envelope = seal(bytes, Buffer.from(key, 'base64'), Buffer.from(plan.keyId, 'hex'), Buffer.from(plan.nonce, 'hex'));
  const partSize = 8 * 1024 * 1024;
  const parts = [];
  for (const [index, url] of plan.parts.entries()) {
    const body = envelope.subarray(index * partSize, (index + 1) * partSize);
    const put = await fetch(url, { method: 'PUT', body });
    if (!put.ok) throw new Error(`part ${index + 1}: ${put.status}`);
    parts.push({ PartNumber: index + 1, ETag: put.headers.get('etag') });
  }
  await callTool('file_complete_upload', { ...where, ticket: plan.ticket, parts });
}

File transfers

Download a file

file_get returns the file’s pieces in order, each with its offset, size, plaintext hash and an envelope URL valid for five minutes. Pass start and end to get only the pieces that cover that byte range.

For each piece, read the key id and nonce from the envelope, fetch the key, decrypt, decompress if gzipped, and verify its SHA-256 against hash. To verify the whole file, concatenate the pieces and check them against the file’s hash.

Keys are safe to cache. A resource’s existing keys never change, and new keys are added alongside them.

download.js
import { createDecipheriv, createHash } from 'node:crypto';
import { gunzipSync } from 'node:zlib';

const where = { project_id: 'b6909c9cf00c1d482686b5f52eadd58e', space_id: '88befbbdf3a1551c4567223ba4d11f90' };
// the whole file; pass start and end for only the pieces holding those bytes
const file = await callTool('file_get', { ...where, id: '496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e' });
const keys = new Map();

// one piece: its envelope's fields read, decrypted, decompressed and checked against its hash
async function piece({ url, hash }) {
  const envelope = Buffer.from(await fetch(url).then(r => r.arrayBuffer()));
  // varints (wire type 0) and byte strings (wire type 2)
  const fields = {};
  for (let at = 0; at < envelope.length;) {
    const varint = () => { let value = 0, scale = 1, byte; do { byte = envelope[at++]; value += (byte & 127) * scale; scale *= 128; } while (byte & 128); return value; };
    const tag = varint();
    if ((tag & 7) === 0) fields[tag >> 3] = varint();
    else { const length = varint(); fields[tag >> 3] = envelope.subarray(at, at + length); at += length; }
  }
  const keyId = fields[7], nonce = fields[6], payload = fields[3], codec = fields[2] ?? 0;
  if (!keys.has(keyId.toString('hex'))) keys.set(keyId.toString('hex'), (await callTool('file_get_key', { ...where, key_id: keyId.toString('hex') })).key);
  const aad = Buffer.alloc(12);
  aad[0] = 1; aad[1] = codec; aad.writeBigUInt64BE(BigInt(fields[1] ?? 0), 2); aad[10] = fields[5]; aad[11] = keyId.length;
  const decipher = createDecipheriv('aes-256-gcm', Buffer.from(keys.get(keyId.toString('hex')), 'base64'), nonce);
  decipher.setAAD(Buffer.concat([aad, keyId]));
  decipher.setAuthTag(payload.subarray(-16));
  const sealed = Buffer.concat([decipher.update(payload.subarray(0, -16)), decipher.final()]);
  const plaintext = codec === 3 ? gunzipSync(sealed) : sealed;
  if (createHash('sha256').update(plaintext).digest('hex') !== hash) throw new Error('piece hash mismatch');
  return plaintext;
}

const content = Buffer.concat(await Promise.all(file.pieces.map(piece)));
if (createHash('sha256').update(content).digest('hex') !== file.hash) throw new Error('hash mismatch');

Tools · Account and projects

whoami

Returns the agent’s organization and access level. For OAuth agents, also returns the person the agent acts on behalf of.

Parameters

None.

Returns

The organization id, the person’s email and id, and access, which is full or a sentence describing the agent’s limits. Agent links act as the organization, so email and id are omitted.

tools/call · whoami
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "whoami",
      "arguments": {}
    }
  }'
Result
{
  "organization": "a3f1c9e07b5d4e2f8c6a1b0d9e8f7c6b",
  "email": "you@example.com",
  "id": "5761e31cd8538b7da8a3ddd4157bd632",
  "access": "full"
}

Tools · Account and projects

list_projects

Lists every project and subproject the agent can open, with the organization’s Home first. Home is a project named Home whose id is the organization’s id, and project_create_space accepts it. It holds resources outside any project and appears only if the agent can open at least one of them. Build the tree from parent_id.

Parameters

archived boolean
Whether to list only archived projects.

Returns

An array of projects.

tools/call · list_projects
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_projects",
      "arguments": {}
    }
  }'
Result
[
  {
    "id": "5761e31cd8538b7da8a3ddd4157bd632",
    "user_id": "5761e31cd8538b7da8a3ddd4157bd632",
    "parent_id": null,
    "name": "Home",
    "pinned": 0,
    "position": "",
    "created_at": "1970-01-01T00:00:00.000Z",
    "archived_at": null,
    "archived_by": null,
    "collaborator": false
  },
  {
    "id": "b6909c9cf00c1d482686b5f52eadd58e",
    "user_id": "5761e31cd8538b7da8a3ddd4157bd632",
    "parent_id": null,
    "name": "Launch plan",
    "pinned": 0,
    "position": "a0",
    "created_at": "2026-09-30T23:46:04.170Z",
    "archived_at": null,
    "archived_by": null,
    "collaborator": false
  },
  {
    "id": "6cf7bac194832dda86975a541d596e05",
    "user_id": "5761e31cd8538b7da8a3ddd4157bd632",
    "parent_id": "b6909c9cf00c1d482686b5f52eadd58e",
    "name": "Website",
    "pinned": 0,
    "position": "a0",
    "created_at": "2026-09-30T23:46:04.199Z",
    "archived_at": null,
    "archived_by": null,
    "collaborator": false
  }
]

Tools · Account and projects

project_create

Creates a root project, or a subproject when parent_id is set.

Requires full access.

Parameters

name string Required
1–200 characters, trimmed.
parent_id string | null
The parent project id. Omit or pass null for a root project.

Returns

The new project.

tools/call · project_create
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "project_create",
      "arguments": {
        "name": "Website",
        "parent_id": "b6909c9cf00c1d482686b5f52eadd58e"
      }
    }
  }'
Result
{
  "id": "6cf7bac194832dda86975a541d596e05",
  "user_id": "5761e31cd8538b7da8a3ddd4157bd632",
  "parent_id": "b6909c9cf00c1d482686b5f52eadd58e",
  "name": "Website",
  "pinned": 0,
  "position": "a0",
  "created_at": "2026-09-30T23:46:04.199Z",
  "archived_at": null,
  "archived_by": null,
  "collaborator": false
}

Tools · Account and projects

list_spaces

Lists the resources in a project that the agent can open. permissions is null for full access, [] for read-only access, or a list of the granted permissions.

Parameters

project_id string Required
The project id.
archived boolean
Whether to list only archived resources.

Returns

An array of resources, each with kind (board, chat, documents, calendar, website, domains or phones) and permissions.

tools/call · list_spaces
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_spaces",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e"
      }
    }
  }'
Result
[
  {
    "id": "37ac76ac06b2d9cca86ef4fb6feb79be",
    "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
    "kind": "board",
    "name": "Roadmap",
    "pinned": 0,
    "position": "a1",
    "created_at": "2026-09-30T23:46:04.232Z",
    "archived_at": null,
    "archived_by": null,
    "permissions": null
  },
  {
    "id": "734c857985a14b1af535621e60590e62",
    "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
    "kind": "chat",
    "name": "General",
    "pinned": 0,
    "position": "a2",
    "created_at": "2026-09-30T23:46:04.259Z",
    "archived_at": null,
    "archived_by": null,
    "permissions": null
  },
  {
    "id": "88befbbdf3a1551c4567223ba4d11f90",
    "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
    "kind": "documents",
    "name": "Specs",
    "pinned": 0,
    "position": "a3",
    "created_at": "2026-09-30T23:46:04.268Z",
    "archived_at": null,
    "archived_by": null,
    "permissions": [
      "upload",
      "delete_own"
    ]
  },
  {
    "id": "c4a1f0e2b7d94e6a8f3b2c1d0e9f8a7b",
    "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
    "kind": "calendar",
    "name": "Team calendar",
    "pinned": 0,
    "position": "a4",
    "created_at": "2026-09-30T23:46:04.274Z",
    "archived_at": null,
    "archived_by": null,
    "permissions": null
  }
]

Tools · Account and projects

project_create_space

Creates a resource in a project. Names must be unique among resources of the same kind in a project. New boards start with the columns To do, In progress and Done. New websites start with a layout, a header snippet, a home page and a /404 page. New calendars use the time zone in the acting person’s profile, if one is set.

Requires full access.

Parameters

project_id string Required
The project id.
kind enum Required
One of board, chat, documents, calendar, website, domains or phones.
name string Required
1–200 characters, trimmed.

Returns

The new resource.

tools/call · project_create_space
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "project_create_space",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "kind": "board",
        "name": "Roadmap"
      }
    }
  }'
Result
{
  "id": "37ac76ac06b2d9cca86ef4fb6feb79be",
  "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
  "kind": "board",
  "name": "Roadmap",
  "pinned": 0,
  "position": "a1",
  "created_at": "2026-09-30T23:46:04.232Z",
  "archived_at": null,
  "archived_by": null
}

Tools · Account and projects

project_rename

Renames a project.

Requires full access.

Parameters

project_id string Required
The project id.
name string Required
1–200 characters, trimmed.

Returns

The project’s id and new name.

tools/call · project_rename
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "project_rename",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "name": "Launch plan"
      }
    }
  }'
Result
{
  "id": "b6909c9cf00c1d482686b5f52eadd58e",
  "name": "Launch plan"
}

Tools · Account and projects

project_archive

Archives a project and its subprojects, hiding them from lists. Pass archived: false to restore them. To list archived projects, call list_projects with archived: true.

Requires full access.

Parameters

project_id string Required
The project id.
archived boolean
Whether to archive (true, the default) or restore (false) the project.

Returns

The project’s id and archived state.

tools/call · project_archive
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "project_archive",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "archived": true
      }
    }
  }'
Result
{
  "id": "b6909c9cf00c1d482686b5f52eadd58e",
  "archived": true
}

Tools · Account and projects

project_rename_space

Renames a resource. Names must be unique among resources of the same kind in a project.

Requires full access.

Parameters

project_id string Required
The project id.
space_id string Required
The resource id, from list_spaces.
name string Required
1–200 characters, trimmed.

Returns

The resource’s id and new name.

tools/call · project_rename_space
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "project_rename_space",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "37ac76ac06b2d9cca86ef4fb6feb79be",
        "name": "Roadmap"
      }
    }
  }'
Result
{
  "id": "37ac76ac06b2d9cca86ef4fb6feb79be",
  "name": "Roadmap"
}

Tools · Account and projects

project_archive_space

Archives a resource. Pass archived: false to restore it. A resource whose project is archived is restored into the nearest project above it that is not, or into Home. To list archived resources, call list_spaces with archived: true.

Requires full access.

Parameters

project_id string Required
The project id.
space_id string Required
The resource id, from list_spaces.
archived boolean
Whether to archive (true, the default) or restore (false) the resource.

Returns

The resource’s id and archived state, and project_id, the project it is in.

tools/call · project_archive_space
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "project_archive_space",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "37ac76ac06b2d9cca86ef4fb6feb79be",
        "archived": true
      }
    }
  }'
Result
{
  "id": "37ac76ac06b2d9cca86ef4fb6feb79be",
  "archived": true,
  "project_id": "b6909c9cf00c1d482686b5f52eadd58e"
}

Tools · Account and projects

list_people

Lists the people who can open a resource, including the organization’s owner, admins and members, and users the resource is shared with. Use their ids in mentions, in assignee and person fields, and as event guests.

Parameters

project_id string Required
The project id.
space_id string Required
The resource id, from list_spaces.

Returns

An array of people, each with id (the account id), name (empty if not set), email and handle (for @ mentions).

tools/call · list_people
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_people",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "734c857985a14b1af535621e60590e62"
      }
    }
  }'
Result
[
  {
    "id": "5761e31cd8538b7da8a3ddd4157bd632",
    "name": "Alex Rivera",
    "email": "you@example.com",
    "handle": "Alex Rivera"
  },
  {
    "id": "b8bc98d760d80b652c1b714e88c31882",
    "name": "",
    "email": "dana@example.com",
    "handle": "dana"
  }
]

Tools · Direct messages

dm_list

Lists the people on the organization’s team, all of whom the agent can message directly.

Parameters

None.

Returns

An array of people, each with id (the account id, used as person_id by the other direct message tools), name (empty if not set), email, unread (messages the agent hasn’t read) and a live status. The status has state (available, busy, away or offline), message (In a meeting during the person’s calendar events, unless they set a custom message) and until (when the status changes automatically, or null).

tools/call · dm_list
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "dm_list",
      "arguments": {}
    }
  }'
Result
[
  {
    "id": "5761e31cd8538b7da8a3ddd4157bd632",
    "name": "Alex Rivera",
    "email": "you@example.com",
    "unread": 2,
    "status": {
      "state": "busy",
      "message": "In a meeting",
      "until": "2026-09-30T23:46:04.000Z"
    }
  },
  {
    "id": "b8bc98d760d80b652c1b714e88c31882",
    "name": "",
    "email": "dana@example.com",
    "unread": 0,
    "status": {
      "state": "away",
      "message": "",
      "until": null
    }
  }
]

Tools · Direct messages

set_status

Sets the agent’s live status, which its team sees in Chat. With auto, the agent appears available for a few minutes after each tool call, then offline. Other statuses apply while the agent is working, until they are changed or clear_at passes.

Parameters

status enum Required
auto, available, busy, away or offline (appear offline while working).
message string
Text shown with the status, up to 40 characters, such as Reviewing pull requests. Omit or leave empty for none.
clear_at string
ISO 8601 time, up to a week ahead, when the status resets to auto with no message. Omit to keep the status until it is changed.

Returns

The status shown to the team (state, message, until, meeting), plus the chosen status and clear_at.

tools/call · set_status
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "set_status",
      "arguments": {
        "status": "busy",
        "message": "Running the nightly import",
        "clear_at": "2026-09-30T23:46:04.000Z"
      }
    }
  }'
Result
{
  "state": "busy",
  "message": "Running the nightly import",
  "until": "2026-09-30T23:46:04.000Z",
  "meeting": false,
  "status": "busy",
  "clear_at": "2026-09-30T23:46:04.000Z"
}

Tools · Direct messages

dm_read

Returns the latest direct messages with one person, oldest first, and marks them read. This resets unread in dm_list.

Parameters

person_id string Required
The person id, from dm_list.
limit integer
Number of messages to return, 1–100. Defaults to 100.

Returns

An array of messages, each with id, body, created_at, sender_name and from_you (true for the agent’s own messages).

tools/call · dm_read
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "dm_read",
      "arguments": {
        "person_id": "5761e31cd8538b7da8a3ddd4157bd632"
      }
    }
  }'
Result
[
  {
    "id": "cef331a96793e1a9c233357773d4942c",
    "body": "Can you sum up what moved on the roadmap this week?",
    "created_at": "2026-09-30T23:46:04.340Z",
    "sender_name": "Alex Rivera",
    "from_you": false
  }
]

Tools · Direct messages

dm_send

Sends a private message to one person. The message appears as unread in Chat until the person reads it.

Parameters

person_id string Required
The person id, from dm_list.
body string Required
1–10,000 characters, trimmed.

Returns

The new message’s id.

tools/call · dm_send
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "dm_send",
      "arguments": {
        "person_id": "5761e31cd8538b7da8a3ddd4157bd632",
        "body": "Three cards moved to Done; the launch checklist is the one left."
      }
    }
  }'
Result
{
  "id": "cef331a96793e1a9c233357773d4942c"
}

Questions or something missing? Contact us.