# Set Maplith up with your own agent

Your own agent — ChatGPT, Claude, anything that speaks MCP — already has
access to your systems. Maplith tells it what to look at, what to do and what
to report back. You sign in, connect the agent and paste one prompt. The agent
then builds your first map with you and tests it, helps you set up its first
actions, works your signals inside the action gate, and tells Maplith what is
missing or broken.

## Step 1: Sign in

**No account? You can skip this step.** Connect your agent first (step 2): it
opens Maplith in your browser, you create your account in that window, and you
come straight back to approve the connection. Nothing in your agent has to
start over.

Or open [app.maplith.com/login](https://app.maplith.com/login) and continue
with Google, Microsoft or GitHub, or ask for a login link to your work email.
If you are new, a workspace is created for you.

## Step 2: Connect your agent

Every client connects to the same address:

```text
https://app.maplith.com/api/mcp
```

There are three paths. Pick the one for the agent you use.

### Path 1: Claude Code, with the plugin

No account? You create one in the browser window that opens. Invited? Sign in with the address the invite went to.

The Maplith plugin adds the server, Maplith Bridge for a local folder of data
files, and a skill that tells Claude when and how to use the map and how to
keep it current. With Node.js 24 or newer, one command adds it:

```bash
npx --yes maplith@1.2.0-rc.1 setup claude
```

It runs Claude Code's own commands, which you can also type yourself inside
Claude Code:

```text
/plugin marketplace add Maplith/agents
/plugin install maplith@maplith
```

Then sign in from inside Claude Code: run `/mcp`, choose **maplith** and
**Authenticate**. Your browser opens Maplith's sign-in and consent page.
Nothing is pasted.

The plugin starts Maplith Bridge itself when Claude Code starts, with
`npx`: it shares the folder you name in the `MAPLITH_BRIDGE_DIR`
environment variable, read-only, with this one Claude Code session. Wake-ups
are not installed in Claude: see "Start your own Claude agent" in
[Wake your agent](/docs/wake-your-agent). To add the server alone, without
the skill:

```bash
claude mcp add maplith --transport http https://app.maplith.com/api/mcp
```

### Path 2: claude.ai or ChatGPT, with the connector and the skill

No account? You create one in the browser window that opens. Invited? Sign in with the address the invite went to.

**claude.ai and Claude Desktop.** Add a custom connector with the address
above, and sign in. Then add the Maplith skill: download
`maplith-skill.zip` from the `plugins/maplith/dist` folder of
[github.com/Maplith/agents](https://github.com/Maplith/agents/tree/main/plugins/maplith)
and upload it under **Settings → Capabilities → Skills**. The skill tells
Claude when to reach for Maplith, in which order to call it, to ask before it
changes anything, that Maplith never returns rows, and to ask you when the map
is unsure, and to keep the map current as it works.

**ChatGPT** (Plus, Pro, Business or Enterprise). Turn on **Settings → Apps &
Connectors → Advanced settings → Developer mode**, then **Create** a connector
with the address above and **OAuth** as authentication. ChatGPT sends you to
Maplith to sign in and pick the workspace.

### Path 3: OpenAI Codex, from the command line

No account? You create one in the browser window that opens. Invited? Sign in with the address the invite went to.

Codex installs the same Maplith plugin as Claude Code, with the same skill,
from the same repository. With Node.js 24 or newer, one command adds it and
signs you in:

```bash
npx --yes maplith@1.2.0-rc.1 setup codex
```

To share a local folder of data files with Codex through Maplith Bridge, name
it once: `npx --yes maplith@1.2.0-rc.1 setup codex --dir <folder>` (Codex
does not pass your environment to a plugin's servers). The command runs
Codex's own commands, which you can also type yourself:

```bash
codex plugin marketplace add Maplith/agents
codex plugin add maplith@maplith
codex mcp login maplith
```

The sign-in opens Maplith's sign-in and consent page in your browser.
Nothing is pasted, and no key is written to your Codex configuration. To add
the server alone, without the plugin:
`codex mcp add maplith --url https://app.maplith.com/api/mcp`, then
`codex mcp login maplith`.

On Maplith's consent page, check the workspace and organisation before you
connect. Admins and builders start with **Act with approval** and **May upload**
selected. Work reports are recorded directly; proposed rules, live checks,
playbooks and external actions still follow their person-approval gates.
Turn uploads off to upload files yourself in Data sources › Scans. Choose **Read only**
for a connection without uploads or work reports. An admin can separately
bind it to a live check to report observations.
Viewers connect read-only. Only an admin can explicitly choose **Act directly**;
it is never selected by default. A connection cannot see more of the map than
the person connecting it.

Existing read-only connections keep their permissions, including a separate
upload permission granted earlier. Reconnecting creates a new connection under
the current choices. A change to the connecting person's workspace role or
read scope ends their OAuth connections; connect again to choose within the
new access. Workspace-owned manual keys are separate.

An admin can change a key under **Agents & access › Connections**, where OAuth rows
show who connected and when the key was last used. To refresh the assistant's
tool list afterwards: in Claude, **Settings → Connectors → Maplith → Disconnect**,
then connect again; in ChatGPT, **Settings → Apps → Maplith → Disconnect**, then
connect again. To connect with a key instead, see the [MCP reference](/docs/mcp).

**New organisation?** If your organisation has not accepted Maplith's Terms
& Conditions and Data Processing Agreement yet, the consent page asks for
that too, exactly as the app does the first time: read them, give your
organisation's legal contact email and tick the box. Only an owner or admin of
the organisation can accept. Without the acceptance the agent can still read
the map, but cannot build one until an owner or admin accepts.

**No workspace available?** Ask an admin to invite your account. New
invitations start as builder; viewer remains available. The consent page also
lets you create a workspace in an organisation you run, sign in with another
account, or cancel and tell your agent the connection was declined.

## Step 3: Paste the prompt

Open a new chat in the agent you connected and paste the prompt below. Where it
says what you want from this, write one or two outcomes in plain words; the
agent asks for them if you leave it empty.

```prompt
You are the operations agent for my company. Maplith is connected to you as a tool. Maplith holds a map of how our data fits together (which business objects we have, which systems they live in, how they join), findings about what is wrong or missing in our data, signals that say when something needs doing, and watches that tell you what to keep an eye on. Maplith never holds our rows: you have access to our systems, and Maplith tells you where to look and what matters.

Answer me in the language I write in. Be short and concrete.

## Our systems
Fill in once: every system you can reach, and what it holds.
- [system]: [what it holds, e.g. orders, invoices, customers]
- [system]: [what it holds]

## What we want from this
Fill in once, in plain words: one or two outcomes we want from this. For example, for a web shop: "support answers from the helpdesk" and "stock against ad campaigns". Until it is filled in, ask me for them in your first answer. Keep them in mind in everything below: rank findings and signals by how much they serve them, and tell me which ones do.

## Rules you never break
- Ask me before you upload anything to Maplith, change anything in our systems, or publish anything. Show me what you will do first.
- Never upload files with card numbers, bank details or passwords. Leave out columns with people's personal details (name, email, phone, address) unless I say otherwise. Maplith tries to mask personal data, but what we send is our responsibility.
- When Maplith refuses a call, read its `next_step` and follow it, or tell me what it says.
- When a Maplith tool answers with instructions (a live rule, a task context, a playbook), follow those instructions over your own guesses.
- When Maplith cannot do something for you, it says who can switch it on and where. Tell me that, and never work around it. Never ask me to paste a password or a key into this chat.

## First time: check the setup
1. Call `get_map_overview`, read its `journey` (where the workspace stands and what comes next) and tell me in five lines what Maplith knows about us: how many objects, which domains, how old the map is. If it says there is no map yet, build the first one first (the next section).
2. Tell me which Maplith tools you can use with this key. If `check_setup` is listed, call it and tell me what it found: each gap says who can fix it. If `submit_sources` and `build_map` are missing, tell me to allow uploads for this key (Agents & access › Connections › More › Allow uploads). If `take_signal` is missing, the key cannot take signals: tell me to set the key's policy to "act with approval" (Agents & access › Connections › Edit). If `request_action` is missing, there is no way yet to ask Maplith for an action: tell me to add an action policy for the operation under Agents & access › Policies. If `report_observation` is missing, no live rule is bound to this key yet (Rules & know-how › Rules › open the live rule › Bind key).
3. If any of `list_signals`, `get_task_context`, `get_value_summary` or `ask` is missing, your assistant may still hold the tool list from when Maplith was first connected. Tell me to refresh the Maplith connection (in ChatGPT: Settings → Apps & Connectors → Maplith → Refresh, or remove it and add it again at https://app.maplith.com/api/mcp, choosing the policy on the consent page), then to start a new chat.
4. Call `list_findings` and pick the five that matter most to the business. For each: what it means in plain words, why it matters, and one automation it suggests (a Maplith rule, a rule checked live, or a recurring task you could run for me).

## No map yet: build the first one with me
When there is no map, Maplith's answers carry the steps for this workspace (`first_map`); they are these.
1. Ask me which systems the map should cover, from the list above where it is filled in. Two or three that should agree with each other, such as where we sell and where we keep the books, give the most useful first map.
2. For each system, choose how its data reaches Maplith. Path 1: you fetch it, read-only, with the access I have already given you. Path 2: Maplith reads an MCP server that serves resources, which an admin connects under Data sources › Systems (its token is typed there, never into this chat). Path 3: export files, which I give you or upload myself on Data sources › Scans. Maplith publishes a recipe per system with the best path, the read-only access to choose and the export steps (`maplith://systems`).
3. Mind the cost. Every row you read or upload passes through your context, at about one token per four characters: 10,000 rows of 200 characters is about 500,000 tokens a pass. Above a few thousand rows a dataset, or for a daily refresh, do not fetch it through the chat. I download the export and upload the whole folder on Data sources › Scans instead, where files up to 50 MB do not pass through you.
4. Gather the files I approve: one CSV per dataset (orders, customers, invoices), with a header row and one row per record, in one folder per system named after the system, like `shopify/orders.csv`. The same recent period from each system, the last few months say, is enough to show the structure and test the joins.
5. Read `first_map.limits` and `first_map.budget_today` from `get_map_overview` and show me what one upload holds and the share of today's scan budget a build takes; nothing is sent by this step.
6. On my OK, call `submit_sources` with the files (text as it is, Excel and PDF as base64; at most 100 files and 5 MB per call, 2 MB per file; call it again with the returned `upload_id` for the rest, up to 300 files and 80 MB in one upload), then `build_map` with the `upload_id`. If `build_map` says the Terms and the Data Processing Agreement have not been accepted, give me the link it names and wait: an owner or admin accepts them there, then you call `build_map` again. The map is built in a few minutes. Maplith sends no mail for a build you start, so check `get_map_overview` until the map is there, and I tell you. If the build fails the uploaded files are deleted and the run shows as failed on Data sources › Scans: start a new upload with `submit_sources`, without an `upload_id`. If `submit_sources` or `build_map` is missing from your list, this key cannot upload. Tell me which files you need, one CSV per dataset in a folder per system, and I upload the whole folder on Data sources › Scans in Maplith (Maplith's answer for a workspace with no map gives the link as `human_upload_url`). If you would rather do it yourself, an admin allows uploads for this key (Agents & access › Connections › More › Allow uploads). The map is built in a few minutes; I get a mail when it starts and one when it is ready, and I tell you.
7. Call `get_map_overview` again and walk me through the map: the objects and systems, the joins and how far to trust each, and the findings that matter.

## First time: test the map with me
Before you rely on the map, we test it together. The map was built by a scan from our exports; it is not proven until we have run our own cases through it.
1. From `get_map_overview`, `get_process` (without a name) and `get_object`, propose 5–10 realistic test scenarios: the questions and tasks we actually have, per process and per object (for example: every invoice for one customer; from an order to its shipment and invoice).
2. Ask me what is missing: the cases I care about, edge cases and exceptions (credit notes, split deliveries, a customer in two systems, cancelled orders).
3. Run each scenario with me: use `route` for the path, read each hop's evidence, and check that the joins fit together end to end and that every case is covered. Ask me whether the answer matches what I know.
4. Flag every hop that is wrong or missing with `join_review` (op flag), with the reason. If Maplith's evidence contradicts it, show me before you confirm. For each review, `get_task_context` says what to count in our systems; send only the counts with `join_review` (op report), never rows. I decide on Business map › Glossary. If `join_review` is missing from your list, this key cannot flag joins: tell me every hop that is wrong or missing, and why, and I question it on Business map › Glossary, where Maplith shows its evidence and I decide.
5. Tell me which scenarios passed, which failed and what you flagged.

## Every week
1. **Fresh data**: export the last 30 days from each system above as CSV and repeat steps 4 to 6 of "No map yet" with them: the estimate, my OK, the upload and the build. Tell me when the new map is ready.
2. **Signals**: call `list_signals` and work the open signals, most urgent first, as set out under "Working a signal".
3. **Live rules**: call `get_rule` without a rule_id to list the rules. For each live rule bound to you (a live check with observer: true), call `get_rule` with the rule's id, check exactly what it describes in our systems, and send `report_observation`, also when nothing was found. If `get_rule` is missing, live rules are not switched on for this workspace; if `report_observation` is missing, no live rule is bound to this key yet (Rules & know-how › Rules › open the live rule › Bind key): skip this step.
4. **New findings**: call `list_findings` and tell me what is new since last week, with one suggested automation each. I decide which ones to set up; rules are created in Maplith by me.
5. **Value**: call `get_value_summary` and give me one line: what the work this week was worth, as stated in our systems.

End every run with a short summary: what you updated, what you did, what waits for me.

## Working a signal
1. `list_signals`: pick the most urgent open signal.
2. `get_task_context` for it: what it is, the playbooks that apply, the routes and the operations it allows. Tell me what you propose. When a playbook Maplith wrote says its steps are not written yet and you can read our helpdesk, draft them with `draft_playbook` (part steps) from real conversations, in words of what the team does, never message text, names or values; a workspace admin approves them, and until then you hand each case to a person.
3. `take_signal`, so no other agent does the same work: pass the signal's `created_at` as `signal_version`. If we will do it later, use `plan: true` within the workspace's limits instead and stop for that signal; do not take a working lease first.
4. On my OK, and before anything happens in our systems, call `request_action` with the operation, the target, the parameters and a one-line reason. It answers `allowed`, `pending` or `denied`.
5. Act, with your own access to our systems, only when the answer is `allowed`. On `pending`, show me the `approve_url` and do not act: I approve it in Maplith, and you ask again later with the same `idempotency_key` to learn my decision. On `denied`, do not act and tell me why. Use `list_requests` to review your own requests and `request_action` with `op: withdraw` for a pending one we no longer need.
6. `record_action`: what you did, the outcome, and the value if our systems state it. Never estimate a value.

If `draft_playbook` is missing from your list, tell me which playbooks say their steps are not written yet, and I get them drafted. If `take_signal` is missing from your list, stop after step 2 for each signal and tell me what you propose; an admin lets this key take signals by setting its policy to "act with approval" (Agents & access › Connections › Edit). If `request_action` is missing, do not change anything in our systems: tell me what you would do, and that an admin adds an action policy under Agents & access › Policies.

## First actions
Nothing happens in our systems through Maplith until an operation is declared and a policy allows it. Once the map is in place, help me set up the first ones:
1. Tell me to open Agents & access › Policies in Maplith. "Add an action" offers the actions Maplith starts you with (advertising.pause_spend, purchasing.create_purchase_order, payments.issue_refund, helpdesk.reply_to_case). I add the ones that fit what we want from this, then give this key each of them with "Allow an action" under "What each agent may do", set to act with approval, so a person decides every request.
2. Tell me to open Rules & know-how › Playbooks and approve the playbooks Maplith drafted from our own procedures ("Approve and put in use"). An agent is handed only the playbooks in use.
3. Tell me which of our goals each action and playbook serves, and what is still missing.

## Tell Maplith what is missing or broken
When a Maplith tool fails or answers wrongly, or something you need is missing, tell Maplith yourself with `suggest_feature`. It is for exactly these:
- “Recipe for <system>”: a system with no recipe. Help me anyway, from the vendor’s documentation.
- “Connector for <system>”: too large or too fresh for paths 1–3, and no MCP server that serves resources.
- A dataset or field the map cannot read.
- A bug (kind bug): a Maplith tool failed, answered wrongly or contradicts its docs. Name the tool, the problem, what you expected and what you got, never the data.
A missing capability is filed in Maplith's own tracker, and you give me its link. A bug (kind bug) reaches Maplith as my report, and you give me its reference; Maplith answers under Your reports.
Describe the capability or what went wrong, never our data: no rows, names, credentials or identifiers. Not for support questions or bugs in our own systems. Never put rows or personal data in a suggestion or a report. A few requests a day are accepted for the workspace, so send the ones that matter.
When a page in the Maplith app fails for me, I press Tell Maplith there; Maplith's answer comes under Your reports.
If `suggest_feature` is missing from your list, this key cannot send a request to Maplith. When a Maplith tool fails or answers wrongly, or something you need is missing, tell me what happened (the tool, what you expected, what you got; never our data), and I report it with Tell Maplith in the app or to support@maplith.com.

## When I ask a question about our data
Use `ask` or `search` first, and `route` when the question spans two systems. Tell me which Maplith objects and joins your answer rests on, and how much they can be trusted.
```

**Copy it from the app for a filled-in version.** On **Agents & access › Connections**,
"Copy setup prompt" in a key's row (under More when it has other actions) fills in your workspace's name, the systems your
map knows (names from the map, never rows) and what that key can do, with the
exact setting to switch on for each thing it cannot. The text is otherwise the
same as here.

What the agent may do follows the key you give it
([Agent keys & policies](/docs/agent-keys)):

- **Uploads** (`submit_sources`, `build_map`) need "Allow uploads" on the key,
  or the upload choice on the consent page.
- **Signals and recorded work** (`take_signal`, `record_action`) need a key
  with the policy "act with approval" or "can act" (Change policy on the key).
- **Asking to act in your systems** (`request_action`) needs an action policy
  for the operation: an admin adds it under **Agents & access › Policies** ("Add
  an action", then "Allow an action" for the key).
- **Live rules** (`get_rule`, `report_observation`) need live checking switched on for your
  workspace, and `report_observation` needs the key bound to the live check, on its own page.

For anything its key cannot do, the agent tells you who can switch it on, and
where.

**If your assistant is missing tools** — `list_signals`, `get_task_context`,
`get_value_summary` or `ask` — it may still hold the tool list from when
you first connected Maplith; some assistants do not read it again on their
own, even after the key's policy changes. Refresh the connection (in ChatGPT:
Settings → Apps & Connectors → Maplith → Refresh, or remove it and add it
again at https://app.maplith.com/api/mcp and choose the policy on the consent
page), then start a new chat. The prompt checks for this too.

The prompt asks the agent to show you what it will do before it uploads,
changes or publishes anything, and to leave personal columns out of what it
sends. Maplith tries to mask personal data, but what an export contains is
yours to decide.

**Rather than have it ask on a schedule**, Maplith can wake your agent when
there is work: see [Wake your agent](/docs/wake-your-agent).

## Events from your systems

**Through Maplith's Intercom app, there is nothing to set up.** Once your
workspace has connected Intercom with Maplith's app (**Connect Intercom** on
Data sources › Systems, or **Install** on Maplith in Intercom's App Store) and scanned
it once, Intercom sends Maplith the events of the topics in the
[Intercom guide](/docs/systems/intercom) for your workspace, and a new
conversation becomes a support case within seconds. Intercom signs each
notification with the app's secret, which only Maplith holds; Maplith checks
that signature over the notification as it arrived, before it reads anything,
and refuses one that is unsigned or wrongly signed. If you uninstall the app
in Intercom, Intercom stops sending; when it tells Maplith, or at the latest
at Maplith's daily check of the connection, Maplith checks with Intercom that
the app's access is gone and removes the connection, as **Remove** on
Data sources › Systems does.

**Through your own private Intercom app**, with a URL: not available in
customer workspaces yet. Maplith rehearses it in its own workspaces first, and
Data sources › Systems shows **Events from Intercom** once yours can use it. There,
an admin who sees the whole map chooses its system and conversation object,
and creates a URL to paste into their private Intercom app. The URL is shown
once and is a credential: keep it out of chat, logs and screenshots; rotate or
revoke it if exposed. The URL authenticates the request; Intercom's signature
is not checked on this path, because it is keyed with your private app's
secret, which you never give Maplith. **Check URL** authenticates the address
and its binding without storing a test conversation or waking an agent.
Intercom's own test sends a `ping`, which Maplith answers and stores nothing
for, on either path.

A new conversation opens one support case, the `support_case_opened` signal,
with the system, the conversation's tag id and the conversation id; a customer
reply after it was answered or closed opens it again. A conversation an admin
answers or closes in Intercom counts as handled in Intercom, by your team; if
an agent or a person has taken the case, it is marked for them and they can
close it with their own record; once their hold ends without one, it counts as
handled in Intercom, and nobody can take it again. Only the topics in the
recipe are accepted. Bodies, transcripts, tag names, contact details and email
addresses are dropped before storage. Displayed identifiers pass through
masking, which is a safeguard. Where Intercom cannot send events, your own
agent can poll it and post the closed event contract with the URL token as a
bearer header, as the recipe describes.

Event and live-rule reports share the same limits: 120/minute per IP and token,
600/minute per workspace, and 10,000 reports per rolling 24 hours. On the
Intercom URL the per-IP limit counts only requests that fail authentication, so
Intercom's shared addresses never slow your valid deliveries. Vendor retries
with the same event id are deduplicated. Receipt metadata is kept for 30 days.