Set up Postware

These are instructions for an agent. The person you work for pasted a prompt asking you to set up Postware. Do the steps in order. Ask the person for one thing only, their email address, in step 5.

If you cannot run shell commands, or this environment loses its files between sessions, go to Chat apps instead.

Postware is a set of standard business data models served by one workspace. You create a real workspace now, with no account, and use it straight away. The person claims it afterwards with one click.

You do not need a .env file. The key is saved in your own MCP settings in step 3.

1. Create the workspace

If you are Claude Code, first check whether this is already connected:

claude mcp get postware >/dev/null 2>&1 && echo "already connected"

If it says already connected, do not create another workspace. Do step 2, then use the Postware tools.

Otherwise, replace PROJECT NAME and run this. With no project, use the name of the person's company or what they are working on, or My workspace if you do not know.

curl -fsS -X POST 'https://api.postware.ai/platform/agent/workspaces' -H 'Content-Type: application/json' -d '{"name":"PROJECT NAME"}'

This creates a real workspace and picks a free address from the name. On 429, wait a minute and run it again.

The response has api_url, mcp_url, api_key, claim_code, claim_url and expires_at. Keep them for this session, and write the real values where this page says API_URL, MCP_URL, API_KEY and CLAIM_CODE. Do not save them to a file or show them to the person.

The workspace is deleted at expires_at, 72 hours after creation, if nobody claims it.

2. Install the skill

Do not skip this. The skill teaches this agent and later ones how to work with the data.

git rev-parse --is-inside-work-tree

If that prints true, this is a project, so write .claude/skills in place of SKILLS_DIR below. If it fails, there is no project, so write ~/.claude/skills, which works from any folder.

mkdir -p SKILLS_DIR/postware && curl -fsS https://postware.ai/docs/skill.md -o SKILLS_DIR/postware/SKILL.md && test -s SKILLS_DIR/postware/SKILL.md && echo "skill installed"

It must print skill installed. If it does not, fix the problem before going on. Read that file now and follow it for the rest of this setup.

For any agent other than Claude Code, add the contents of https://postware.ai/docs/skill.md to AGENTS.md, or to the agent's global instructions when there is no project.

3. Connect the agent

Add the MCP server, so later sessions can use the workspace. This is where the key is kept.

For Claude Code in a project, run this. With no project, add --scope user after add so it works from any folder.

claude mcp add --transport http postware "MCP_URL" --header "Authorization: Bearer API_KEY"

Then check it:

claude mcp get postware >/dev/null && echo "connected"

For Cursor, add this to ~/.cursor/mcp.json, with the real values. That file is outside the project, so the key cannot be committed.

{
  "mcpServers": {
    "postware": {
      "url": "MCP_URL",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

For any other client, put the same URL and Authorization header in its own settings, never in a file git tracks. Connect your AI has the steps for each one.

Clients usually load MCP servers at startup, so keep using the HTTP API for the rest of this session.

In a project, also add this to AGENTS.md or CLAUDE.md, creating the file if needed:

## Business data

This project keeps its business data in Postware, using the MCP server `postware`. Read the schema before writing records. Reference: https://postware.ai/llms.txt

Only if the project's own code will call Postware, add POSTWARE_API_URL and POSTWARE_API_KEY to its environment, the way it already keeps secrets. Nothing else needs them.

4. Set up the workspace

Read the schema first, then create what the project needs. Every workspace has all the models: core, CRM, Billing, Support and Content.

curl -sS "API_URL/schema" -H "Authorization: Bearer API_KEY"

Each model's identity rules, required fields and status categories are in its reference page. The API reference covers queries, writes and imports.

5. Ask for the claim

When the setup is done, or a request answers claim_required, ask the person which email should own the workspace. Suggest the one from git config user.email if there is one. Then send it:

curl -sS -X POST https://api.postware.ai/platform/agent/claim \
  -H "Authorization: Bearer CLAIM_CODE" \
  -H 'Content-Type: application/json' \
  -d '{"email":"person@example.com"}'

Tell the person to open the email, follow the link and press Approve. Approving accepts the terms of service, which only they can do. Addresses containing + and disposable addresses are refused, so ask for another one if that happens.

To see whether they have finished, check claimed:

curl -sS https://api.postware.ai/platform/agent/claim -H "Authorization: Bearer CLAIM_CODE"

The Free plan includes one workspace per account. If the person is at the limit, Approve explains the options. If you cannot ask them, give them claim_url before this session ends, because the claim code is not saved anywhere.

Never enter a card or choose a paid plan. Plans are the person's decision, on the dashboard.

Finish by telling the person that the skill is installed and the Postware tools will appear the next time they start this agent.

Chat apps

A chat app with no shell cannot create a workspace or keep a key, so the person connects it. Tell them to:

1. Sign up at https://postware.ai/dashboard and create a workspace. The Free plan needs no card.
2. Open the workspace's Connect page, choose Chat apps and copy the URL.
3. Add a custom connector with that URL in the chat app. In Claude, that is Customize, then Connectors, then Add custom connector. Connect your AI has the steps for others.
4. Sign in with their email and press Allow.

Then use the Postware tools, starting with the schema. There is no skill file to install here: the connector tells you how to use the workspace when it connects.

What waits for the claim

An unclaimed workspace is a private workspace for you and your key.

Your key reads and writes records, imports and exports. These need a claim, because they reach people: sign-in for end users, emails, share links and public pages. Inviting members, webhooks and new extensions need an owner, so the person does those after claiming, or issues you a key with more access.

Errors

Errors are JSON: {"error":{"code":"...","message":"..."}}.