API & MCP guide

Connect with API & MCP.

Connect a supported AI once, then call your personal or company workflows and skills by name. Your AI reads their saved instructions and text files, then runs the authorized work with its own tools.

Connect your AI Read the API docs OpenAPI schema

Your AI account pays for its work. AI Blocks serves the skills, files and workflow plans.

Choose the work your AI can read

MCP is a way to connect an AI to tools and files. Add one of these server URLs in your AI tool's connection settings.

Public library

Find skills for a new task

Search published skills and build a workflow in your AI. Public access does not need sign-in.

https://useaiblocks.com/mcp

Your saved work

Reuse your saved workflows

Read your account's saved skills, workflows, kits and profiles. Sign in to AI Blocks when your AI asks.

https://useaiblocks.com/mcp/personal

Your company Space

Use your team's saved work

This URL opens your own Space. To read another company Space, use the full URL its owner gives you.

https://useaiblocks.com/mcp/company

For a selected company Space, the owner gives you a URL ending in /mcp/company/{connection-token}. You must also sign in with an allowed work account. The owner controls access.

For private work, choose OAuth sign-in and automatic client registration (DCR). Use a separate connection for personal and company work.

Add the connection to your AI tool

Your app needs remote MCP over Streamable HTTP. Its plan and workspace settings must allow custom connections. The skills you run may also need files, a browser or other tools.

CodexCompany workflow tested

Add your personal library, then sign in:

codex mcp add ai-blocks-personal --url https://useaiblocks.com/mcp/personal --oauth-resource https://useaiblocks.com/mcp/personal --oauth-client-registration dcr
codex mcp login ai-blocks-personal --scopes saved:read --oauth-client-registration dcr

For company work, use its full URL, a different name and company:read. For public skills, add https://useaiblocks.com/mcp without sign-in. Check your installed CLI's help for the flags it supports.

Official Codex setup

ChatGPT webSaved work tested

Open Plugins → Add → Add custom MCP server in an account or workspace with custom MCP access.
Enter the server URL. Choose OAuth for private work, or no authentication for public skills.
Review Advanced OAuth settings. Use Dynamic Client Registration (DCR) and the matching default scope: company:read or saved:read.
Create the plugin, connect its app, and finish AI Blocks sign-in and consent. Choose Try in chat for the first request.

Our Pro account passed two company runs and two personal runs. Each library passed a fresh-chat repeat using its existing connection. Personal runs found the attached skill separately and read all seven resource entries. ChatGPT's tools ran the approved steps and checked the results. If it does not select the connection, name it or use @ to choose the installed plugin. Plan, admin and security rules still apply; private URLs need OAuth for the whole connection.

Official ChatGPT setup

ClaudeSaved work tested

Open Customize → Connectors → Add custom connector.
Enter the server URL and choose Sign in now for private work.
For the OAuth client, choose Register automatically. Sign in, then enable the connector in your chat.

Team and Enterprise accounts need an owner or allowed admin to add the connector first. Members sign in individually. Our Free account with Sonnet 5.5 Medium passed two company runs and two personal runs, including a fresh chat for each. The personal runs loaded the saved skill and all seven resource entries, then calculated and checked the result in Claude's tools. Normal Allow once prompts remained enabled.

Free currently permits one custom connector. We switched from company to personal with the owner's approval; keeping both separate endpoints installed was not tested on Free. Switching back requires reconnecting, while saved data stays intact. An installed connector may need enabling in a chat. Your Claude account needs available model usage; API Console credits are separate.

Official Claude setup

Claude CodeSetup documented

Add the HTTP server, then open /mcp in Claude Code to sign in:

claude mcp add --transport http ai-blocks-personal https://useaiblocks.com/mcp/personal

If you set oauth.scopes, use saved:read for personal work or company:read for a company Space. Keep each in its own connection. Your organization's tool rules still apply. AI Blocks has not yet been tested in this client.

Official Claude Code setup

DeepSeek and custom AI appsBridge needed

A developer can connect an app that uses DeepSeek through our API or an MCP client. The app receives the AI's tool request, calls AI Blocks and sends the result back to the AI.

The app must handle each user's sign-in, file reads and tool calls. This bridge runs in the customer's environment. We have not verified a native connection in the DeepSeek chat website or shipped a DeepSeek adapter.

Official DeepSeek tool-calling guide · API routes below

Personal and company reuse tested

ChatGPT and Claude web each completed two company runs and two personal runs with illustrative saved workflows. Each pair included a fresh chat using the existing connection. Their tools executed calculation and independent verification. Personal runs read seven workflow/skill resource entries; company runs read five. Codex also passed two company staging runs.

What these checks cover

These checks cover the named fixtures and clients, including independent personal skill discovery and use inside the workflow. They do not certify every workflow, plan or standalone skill task. Claude Code and DeepSeek guidance remains separate from a completed client test.

Call your saved workflows and skills

After connecting ChatGPT, Claude or another compatible AI, choose a prompt below. Replace the brackets with your saved name or ID and task. A fresh chat needs that name or ID because it may not know your earlier conversation.

Personal workflow: first run

Use my AI Blocks personal connection to find “[workflow name or saved ID]”. Read its full saved workflow, attached skills and required files. Show the IDs, versions, chosen skills and blockers. My task is [task]. Keep its saved steps and dependencies. Ask for missing required facts and approvals, then run the authorized work with your tools and report the actual checks.

Personal workflow: fresh chat

Use my existing AI Blocks personal connection to run “[workflow name or saved ID]” for [new task]. Retrieve its current steps, attached skills and required files. Compare with [last version, if available] and show changes before running. Keep the saved structure, resolve missing inputs and approvals, then execute and check the authorized work.

Company workflow: first run

Use my AI Blocks company connection for “[company Space]” to find “[workflow name or saved ID]”. Retrieve its full steps, mapped skills, profiles and required files. Show the chosen items, versions and blockers. My task is [task]. Ask for missing required facts and approvals, then run the authorized steps with my tools and check the results.

Company workflow: fresh chat

Through my existing AI Blocks company connection for “[company Space]”, run “[workflow name or saved ID]” for [new task]. Read the current saved workflow and its skills and files. Compare with [last version, if available] and show changes. Keep its structure, resolve required inputs and approvals, then execute and verify the work.

Saved skill: first use

Use my AI Blocks [personal or company] connection to find the saved skill “[skill name or saved ID]”. Read its full instructions and every required reference through the connection. Show its ID, version and required inputs. Apply it to [task] with my authorized tools, ask for anything missing, and report the result and actual checks.

Saved skill: fresh chat

Use my existing AI Blocks [personal or company] connection to load “[skill name or saved ID]” again for [new task]. Read its current instructions and required files. Show any change from [last version, if available], resolve required inputs and approvals, then apply the skill and check its output.

Your AI retrieves the saved workflow, attached skills and supported text references automatically. Review the imported skills and versions before work begins. A standalone skill can be read and used directly; it does not need a new workflow.

Normal tool approvals or enabling an installed connector may still be needed in a fresh chat. Sign-in and company membership must stay valid. Expired or revoked access, a removed connector or a rotated company URL requires reconnecting. Device-only saves must first be synced in AI Blocks.

Bring the facts the job needs

Your brief, brand files or business data stay in the tools you authorize. Your AI asks for missing required facts.

Review the skills it chooses

For a new workflow, ask your AI to propose steps and skills. Choose replacements or edits before it prepares the plan.

Keep changes in your AI

Ask for a replacement skill or local edit, review the revised plan and prepare it again before running affected steps. To save the edit back to AI Blocks, use the app's save controls.

Build the same connection into your app

The API lets your app find saved work, read its files and prepare it for your AI. Your app supplies the AI and the tools that do the job.

Try the public API

No account or API key is required for the public library. Search first, then use a returned slug and revision_sha256 to retrieve the full instructions.

curl 'https://useaiblocks.com/api/v1/search?query=writing&type=skill&limit=5'

const base = 'https://useaiblocks.com/api/v1';
const response = await fetch(`${base}/search?query=writing&type=skill&limit=5`);
if (!response.ok) throw new Error(`Search failed: ${response.status}`);
const { items } = await response.json();
if (items.length) {
  const { slug, revision_sha256 } = items[0];
  const skill = await fetch(`${base}/skills/${slug}?revision_sha256=${revision_sha256}`);
  if (!skill.ok) throw new Error(`Skill retrieval failed: ${skill.status}`);
  console.log(await skill.json());
}

Public REST reference

Method and path	Purpose	Arguments
`GET /api/v1/status`	Check public API capabilities.	None. Open status.
`GET /api/v1/search`	Find published skills and workflows.	`query`, `type`, `category`, `limit` (1–25), `offset`. Follow `next_offset` until null.
`GET /api/v1/skills/{slug}`	Read skill instructions and its file inventory.	Optional `revision_sha256` pins the selected version.
`GET /api/v1/workflows/{slug}`	Read a workflow and its ordered skill references.	Optional `revision_sha256`.
`GET /api/v1/resources/{slug}`	Read a supporting text file.	`path`, `revision_sha256`, optional `offset` and `limit`. Follow all chunks.
`POST /api/v1/workflow-preparations`	Validate a proposed workflow and prepare an unsaved draft.	Send JSON with `Content-Type: application/json`. See the schema for the complete preparation body.

Private API and authentication

Read from	REST base URL	Sign-in scope
Public library	`https://useaiblocks.com/api/v1`	Public access
Personal saves	`https://useaiblocks.com/api/v1/personal`	`saved:read`
Your own Space	`https://useaiblocks.com/api/v1/company`	`company:read`
Selected company Space	`https://useaiblocks.com/api/v1/company/{connection-token}`	`company:read`

See saved-work API calls and sign-in details

Use the personal or company base URL above for these private routes:

GET  BASE/items?query=review&kind=workflow
GET  BASE/items?query=review&kind=skill
GET  BASE/items/{item_id}
GET  BASE/resources/{item_id}?path=item-data.json&revision_sha256={sha}
POST BASE/workflow-preparations

Preparation body:
{ "item_id": "…", "revision_sha256": "…" }

Keep OAuth tokens in your app's secure store. Send the access token in the Authorization header. It must belong to the matching MCP resource and user.
Private files use base64 byte chunks. Join them in order until next_offset is null. Check the full byte count and SHA-256 hash. Public text offsets count Unicode code points.
Keep the returned file and workflow versions. A change needs a fresh read and review. A prepared plan does not prove that a step ran.
Personal skills use list_saved_items with kind: "skill", then get_saved_item and get_saved_resource. Company skills use the matching company tools. Embedded personal skills include saved_origin to identify their workflow.
Each private MCP connection has four saved-work tools and the five public tools. Read tools/list for their exact schemas.

Open the public OpenAPI schema · Open OAuth server details

Your AI must have the tools and files required by each step. Missing required files or tools block that step. The connection reads saved text resources; private binary file storage is not supported yet.

The MCP tools read and prepare work. Your AI follows your permissions and the workflow's checks. Its subscription or API account pays for its work. AI Blocks still pays for ordinary API, database and sign-in infrastructure. Saving an item does not start a background run.

MCP tool reference

Use a remote MCP client with Streamable HTTP. The public server is https://useaiblocks.com/mcp. Connect through your client's MCP settings, then use tools/list to discover the current argument schemas.

Tool	What it returns
`search_library`	Public catalogue matches, slugs and revision hashes.
`get_skill`	Full skill instructions and supporting-file inventory.
`get_workflow`	Workflow definition, governing instructions and ordered skill references.
`get_resource`	A chunk of a supporting text file. Fetch every chunk before using the file.
`prepare_workflow`	A validated draft for the host AI to review and run with your authorization.

Personal and company connections add four saved-work tools to these five public tools. Each private connection requires its own matching OAuth resource and scope. The connection reads and prepares work; it does not save edits or run steps on the server.

Troubleshooting

Response or symptom	What to do
`400` / invalid arguments	Check the OpenAPI schema or MCP tool schema. Use the exact argument names and valid ranges.
`401` / sign-in needed	Reconnect the private server through OAuth. Use `saved:read` for personal work or `company:read` for company work.
`403` / access denied	Check the signed-in account and company Space permissions with its owner.
`404` / not found	Search again and use the returned slug or saved item ID. Public and saved-work routes have different identifiers.
`409` / stale revision	Retrieve the current version and review the changes before preparing the workflow again.
`429` / rate limited	Pause requests and retry with backoff. Avoid repeated parallel searches.
`503` / unavailable	Retry later. A failed retrieval does not mean the workflow ran.
Opening an MCP URL in a browser fails	Add the URL to an MCP client. It is a protocol endpoint; use this guide for human-readable documentation.

Need help? Contact support with the route, response code and time of the request.