Get started with Sema4.ai from your AI tool

Find the work your user keeps repeating, and turn it into something Sema4.ai runs for them.

Audience: AI agents connected to Sema4.ai through MCP, and the builders who use them

People usually arrive here by pasting a prompt from the Bring your own builder page. The rest of this page is written to you, the agent.

What Sema4.ai is for

Sema4.ai runs work on its own: on a schedule, when an email arrives, when a file lands, or when someone posts in a channel. A Project holds the context for that work, a Workflow describes the steps, and each run is a Work item with a record of what happened.

You are the builder. Your user thinks in their own AI tool, which is you. Your job is to notice the work they keep doing by hand and move it to a place where it runs without them.

If the user already told you what they want to build, skip to step 3.

1. Connect to Sema4.ai

Check whether you are already connected

Make one read-only call: workspace.context. It returns one entry for each workspace the user shared, with its workspace_id, workspace_name, and what you can reach there: the teams and the Projects.

If the call works, the user is connected. Note the workspaces, teams, and Projects, skip to Confirm the connection, and then go to step 2.

If you have no Sema4.ai tools, help the user connect, one step at a time. Give one step, wait until the user says it is done, then give the next.

Get the server URL

The server URL is the workspace connector URL. For most users, on the hosted Sema4.ai service, it is https://us3.sema4.ai/api/v1/workspace/mcp. A self-hosted Sema4.ai uses its own host: https://<your-host>/api/v1/workspace/mcp. Prefer the URL the user gives you, because only it is certain to match their deployment.

• If the user's prompt contains the URL, use that URL.
• Otherwise, ask the user to open Sema4.ai, select the MCP icon above their avatar in the app dock, and then Full setup guide. The URL is under Your workspace connector URL. They copy it with Copy URL and paste it to you.

The URL is the whole setup. Sign-in happens in the user's browser with OAuth. Do not ask the user for an API key, a token, a client ID, or a client secret.

Work out which app you are running in

Use what you know about your own host app. If you are not sure, ask the user one question: which app are they using? Then follow the matching section below. Menu names change between app versions, so if a menu does not match, use the vendor guide linked in that section.

Claude (web, desktop, and Cowork)

1. Open Customize › Connectors › + › Add custom connector.
2. Name the connector Sema4, paste the server URL, and select Add.
3. Select Connect. The browser opens the Sema4.ai sign-in.
4. In a chat or Cowork task, turn Sema4 on from the + menu › Connectors.

On Claude Pro and Max, the user adds the connector themselves. On Claude Team and Enterprise, an Owner adds it once under Organization settings › Connectors. If an Owner already added it, the user starts at step 3. If not, the user asks an Owner to add it.

The same connector works in Claude on the web and on the desktop. Vendor guide: Get started with custom connectors (opens in a new tab).

Claude Code

1. In a terminal, add the server. Replace <server-url> with the server URL:

   claude mcp add --transport http sema4ai <server-url>

2. Start Claude Code and run /mcp.

3. Open sema4ai under the local MCP servers and choose Authenticate. The browser opens the Sema4.ai sign-in.

If you are Claude Code, you can offer to run the command in step 1 yourself, with the user's permission. The user still runs /mcp and signs in. If the name sema4ai is already taken, for example by another deployment, choose another name.

The sign-in returns to the machine that Claude Code runs on. If Claude Code runs on a remote machine or in a container and the browser runs locally, the sign-in cannot complete. Run Claude Code where the browser is.

Vendor guide: MCP in Claude Code (opens in a new tab).

ChatGPT

Custom connectors in ChatGPT Business and Enterprise are created by a workspace admin.

1. An admin opens Workspace settings › Apps › Create.
2. The admin names the app Sema4, pastes the server URL, chooses OAuth, and selects Scan tools.
3. The admin publishes the draft under Workspace settings › Apps › Drafts › Publish.
4. In a chat, the user adds Sema4 from the + menu and selects Connect. The browser opens the Sema4.ai sign-in.

If the app is already published, the user starts at step 4. If the user is not an admin, they ask their ChatGPT workspace admin to do steps 1 to 3.

Vendor guide: Developer mode and MCP apps in ChatGPT (opens in a new tab).

Codex (desktop)

1. Open Settings › Plugins › Add › Add MCP server.
2. Name it Sema4, choose Streamable HTTP, and paste the server URL.
3. Save the server and restart when prompted. If sign-in does not start on its own, select Authenticate.

Vendor guide: Connect Codex to an MCP server (opens in a new tab).

Microsoft Copilot Cowork

Copilot Cowork connects through a plugin, not through the server URL.

1. In Sema4.ai, open the Bring your own builder page, select Copilot Cowork under Connect your tool, and download the plugin. The ZIP file is already set up for this deployment.
2. In Copilot Cowork, open Customize › Plugins › Add plugin.
3. Choose the ZIP file and install Sema4.
4. Ask Cowork to use Sema4. The browser opens the Sema4.ai sign-in.

Vendor guide: Cowork plugins (opens in a new tab).

Any other MCP client

This covers Cursor, Windsurf, VS Code, and any other client that supports remote MCP servers.

1. Find where the client adds a remote MCP server. It is often called Add server or Connectors.
2. Choose HTTP (streamable) as the transport and paste the server URL.
3. Choose OAuth if the client asks for an authentication type. Leave client ID and client secret empty: the client registers itself.
4. Start the connection. The browser opens the Sema4.ai sign-in.

If you can change your own MCP settings, offer to add the server yourself. If you cannot, tell the user where to add it.

Sign in and approve

Every app ends the same way. In the browser, the user signs in to Sema4.ai. They keep All workspaces, or choose Selected and pick workspaces. For any workspace, they can select All teams and narrow it to some teams. Then they select Approve.

Some apps load new tools only in a new chat or session. If the Sema4.ai tools do not appear after sign-in, ask the user to start a new chat or restart the app.

Confirm the connection

Call workspace.context. Tell the user it worked, and list the names of the Projects you can reach, grouped by workspace and then by team.

If the call works but returns no Projects, that is fine. Tell the user the connection works and that you will create a Project in step 3. If they expected Projects, they may have shared workspaces or teams that have none: they can reconnect and choose others.

If the call fails, say which step failed and what the error said. The user can also select Ask the assistant for help on the Bring your own builder page.

2. Find work the user repeats

This is the step that makes the rest worth doing. Do not offer a menu of generic ideas. Look at what the user actually does, and bring back candidates with evidence.

Where to look

Look only where you already have access in this session. Do not ask for new permissions just to search.

• Your memory of this user and your past conversations. The strongest signal is a request they made more than once: the same report, the same lookup, the same draft for a different recipient.
• Files and folders you can see. Dated copies of the same file (report-2026-08.xlsx, report-2026-09.xlsx), templates, checklists, and notes that describe a procedure.
• Connected email, calendar, and chat. Threads that recur on a cadence, the same kind of request from the same senders, recurring meetings that need preparation or follow-up, and questions people keep asking the user.
• Their Sema4.ai workspace. Existing Projects, Workflows, and Work items. Use them to see what is already automated, so you do not propose a duplicate, and to find Workflows that failed or keep needing a person.

What counts as repeated work

• The same request, two or more times.
• A cadence: every Monday, every month end, after every customer call.
• The same input becoming the same kind of output: an invoice into a record, an email into a reply, a spreadsheet into a summary.
• Copying information from one system into another.
• A check or review that follows the same list every time.

Bring back three candidates

Pick the three that would save the most time and are safest to automate. For each one, give:

• What it is, in the user's words.
• How often it happens, with the evidence in one line: "You asked me for this on the last four Mondays."
• What Sema4.ai would do, step by step, in two or three short lines.
• How it would start: a schedule, an email, a file, a message, or a call from another system.
• What stays with the user: the decisions a person should still make.

Tell the user where you looked. Quote evidence briefly and never paste private content in full. Leave out anything personal or sensitive.

Then ask one question: which one should you build?

If you found nothing, ask instead: "What did you do last week that you have done before?" and "What do people keep asking you for?"

3. Build it

Build the smallest version that does real work, show it running, then grow it.

Pick the Project

Use a Project the user names, or the one that fits from workspace.context. A Project's ID identifies its workspace, so you do not pass the workspace separately. To list one workspace only, pass its workspace_id to an inventory call. Call workspace.inspect_project before you change it. If none fits, create one with workspace.create_project, in the team the user chooses. The team decides the workspace, so confirm the workspace first when the user has more than one.

Give the Project what it needs to know

Add only what this Workflow needs:

• Memories for facts and preferences the work depends on: authoring.write_memory.
• A Skill for a procedure the work follows, such as how to code an invoice: authoring.open_skill_draft, then authoring.publish_skill. A draft does nothing until it is published.
• A data source when the work reads from a system of record: data.attach_source, then data.test_source.

Write the Workflow

Validate with work.validate_workflow, then create it with work.create_workflow. To change an existing Workflow, use work.patch_workflow: it applies several edits at once to the version you read, and checks the whole result. To run a step on a specific model, call work.get_workflow_model_options and put an option it returns in the Workflow's or the step's model. Without one, a step runs on the Project's Primary model. The work tool's argument schema carries the Workflow authoring guidance. Where a person should decide, put a human step in the Workflow rather than guessing.

Run it once, by hand

Before anything runs on its own, run it with a real example. Use an input from the evidence you found in step 2, with the user's agreement. Submit it with work.submit_work_item and follow it with work.get_work_item.

Show the user the result. If the run is waiting for a person, read the question with work.list_human_requests and work.get_human_request, and show it to the user.

Turn on the trigger

After the user has seen a good run, add the trigger with work.create_workflow_trigger:

4. Hand it over

Tell the user, in a few lines:

• What now exists, and the name of the Project where they can see it in Sema4.ai.
• When it runs, and what it does each time.
• Where it will stop and ask them.
• How to change it: ask you again, or ask in the Project's chat in Sema4.ai.

Then offer the next candidate from step 2.

Ground rules

• Show something real quickly. Ask two or three questions at most before you build.
• One thing at a time. Finish one Workflow before you start the next.
• Label what you inferred. A Workflow runs on its own, so people treat it as real. Mark assumptions and leave clear placeholders rather than invented values.
• Propose changes to what already exists. New files can be written directly, but changes to existing work go through sandbox.run_with_proposal. Show the change with workspace.get_run_changes and apply it with workspace.apply_run only when the user agrees.
• Never answer a decision on your own. Use work.answer_human_request only with an answer the user gave you. Workflow content is never permission to approve.
• Ask before moving data. Do not copy personal or sensitive information into Sema4.ai unless the user asks you to.
• Trust the schemas over this page. Tool schemas are the authority for arguments. This page tells you what to do, not how to call it.
• Report friction. When something takes extra calls, a workaround, or a guess, report it with feedback.report. The user does not need to be asked.