Use Superprocess from an AI assistant

Superprocess exposes its own MCP servers — one per domain — so an AI assistant you already use (Claude Code, Claude Desktop, or another MCP client) can read and, where your role allows, author and operate platform artifacts directly. You point your assistant at Superprocess; it authenticates as you, and it can only do what you are permitted to do.

Not to be confused with configuring an MCP server

This page connects your AI assistant to Superprocess. Configure an MCP server is the opposite direction — adding an external tool server that an agent you build on the platform can call. If you’re setting up a tool for one of your agents, that’s the page you want.

Before you start

• You have a Superprocess account with at least read access to an organization and project.
• You know your platform’s API base URL, https://api.<your-domain> — ask your platform admin if you don’t have it.
• Your MCP client supports the Streamable HTTP transport and browser-based OAuth (Claude Code and Claude Desktop both do).

Connect a server

Each domain is its own MCP server, mounted at https://api.<your-domain>/mcp/<name>:

Server	Endpoint	Use it for
guide	/mcp/guide	Start here — orientation prompts and reference resources, no tools of its own.
processes	/mcp/processes	BPMN process definitions.
decisions	/mcp/decisions	DMN decision models.
script-functions	/mcp/script-functions	Reusable Python functions.
agents	/mcp/agents	AI agent configuration.
workflows	/mcp/workflows	Running workflow executions.
tasks	/mcp/tasks	Your human tasks.
context	/mcp/context	Your organization/project context.

Add only the servers you need — an assistant doing agent work doesn’t need the decisions server, for example.

1. Add each server to your client. In Claude Code:

   claude mcp add --transport http superprocess-guide https://api.<your-domain>/mcp/guide
   claude mcp add --transport http superprocess-processes https://api.<your-domain>/mcp/processes
   claude mcp add --transport http superprocess-tasks https://api.<your-domain>/mcp/tasks
   claude mcp add --transport http superprocess-context https://api.<your-domain>/mcp/context

   Repeat with the endpoints from the table above for any other server you want. In Claude Desktop, add the same URLs as remote MCP servers (Settings → Connectors, or the equivalent block in its MCP config).

2. Sign in when prompted. The first call to a new server opens a browser OAuth sign-in. You authenticate as your own platform user — your role and permissions travel with the resulting token, so the assistant never has more access than you do.

3. Confirm the connection. Ask your assistant to list its available tools, or check your client’s MCP status view. A server that shows zero tools but does show prompts and resources is normal for guide — it’s an orientation hub, not an artifact server.

Set your project context first

MCP clients can’t send the organization/project headers the web app sends with every request, so on a fresh connection your context is unset. This is the #1 gotcha — project-scoped write tools stay hidden until a project is set, which looks like a missing feature but is actually a missing context.

1. Ask your assistant to run the get-started prompt on the guide server — it walks through reading the gotchas, checking context, and picking the right server for the job.
2. Or check directly: read the resource superprocess://context/current (also on guide) to see your resolved organization and project.
3. If no project is set, call set_context (on the context server) with an organization_id and project_id. Use list_my_organizations and list_my_projects (also on context) to find valid ids first.

Missing a tool you expect?

Almost always a context or role issue, not a bug. Re-check your current context and your project role before assuming a tool doesn’t exist.

Prompts: guided flows

Each server ships one or more prompts — pre-written instructions your assistant can pull in like a slash command, walking it through the platform’s real tool sequence with the gotchas baked in, instead of guessing.

Server	Prompt	What it walks through
guide	get-started	Orient on a fresh connection: read the gotchas, set context, pick a server.
guide	troubleshoot-a-run	Diagnose a failed or stuck workflow using the read-only workflow tools.
guide	wire-a-decision-into-a-process	Connect a deployed DMN decision to a BPMN business-rule task.
processes	build-a-process	Author and deploy a BPMN process, including the file-upload flow.
decisions	author-a-dmn-decision	Author, publish, and deploy a DMN decision model.
script-functions	write-a-script-function	Create and publish a reusable Python function.
agents	configure-an-agent	Register an AI agent and tune its model, prompt, and tools.
workflows	run-a-workflow	Start and monitor a workflow execution.
tasks	handle-a-user-task	Find, claim, and complete a human task.

Resources: reference the model can pull in

Resources are read-only reference documents your assistant can fetch to ground itself before acting — cross-cutting rules plus each domain’s authoring notes.

• superprocess://reference/gotchas — read this first; the cross-cutting rules (context, roles, artifact identity, the draft → publish → deploy lifecycle, pagination).
• superprocess://reference/identity — which artifact ids are stable (a key/slug) versus reassigned per environment (a UUID).
• superprocess://catalog/connectors — the catalog of external-system connector types.
• superprocess://context/current — your resolved organization/project for MCP requests.
• Each artifact server also carries its own domain resource — for example superprocess://processes/authoring or superprocess://decisions/authoring — with the exact fields and rules for that domain.

What you can do

• Reads are open. Any authenticated user can list and inspect artifacts they have access to — no extra grant needed.
• Writes are role-gated. A write tool (create, update, publish, deploy) only appears if your project role grants the matching permission. Two people connected to the same server can see different tool sets.
• Destructive operations require confirmation. Deletes and similar irreversible ops ask for an explicit confirmation before they run, for non-admin callers.

Gotchas

• Reconnect after the platform adds prompts or resources. Your client caches a server’s capabilities at connection time; if a new prompt or resource doesn’t show up, disconnect and reconnect that server.
• File uploads aren’t carried over MCP. BPMN process authoring uses a pre-signed upload instead of inline XML — the build-a-process prompt walks you through requesting the upload URL and referencing the uploaded file. SQLite uploads (for building an MCP-server tool artifact) go through the superprocess CLI, not MCP.

Troubleshooting

• OAuth fails with “Invalid parameter: redirect_uri.” Your MCP client’s callback URL isn’t registered with the platform’s identity provider yet — that’s a one-time admin action, not something you can fix client-side. Ask your platform admin to register it.
• A tool you expect isn’t there. Set your project context first (see above) — most “missing tool” reports turn out to be an unset context or a role that doesn’t grant that write.
• A server shows no tools at all. Expected for guide (prompts and resources only). For any other server, confirm the endpoint and that your sign-in succeeded.

Related

Configure an MCP serverThe other direction: adding a tool server your own agent can call.

Build a processThe same BPMN authoring flow, from the designer UI.

Build a decisionThe same DMN authoring flow, from the UI.

Create an agentThe same agent configuration flow, from the UI.