---
name: orgtools-mcp-setup
description: Connect an AI agent to Orgtools over MCP. Signs the person in or registers them at orgtools.com, adds the Orgtools MCP server to the agent's own client with OAuth in the browser, and proves the connection with a whoami call. Use when a person asks to set up, connect, or install Orgtools in Claude Code, Codex, Cursor, or any other MCP client.
metadata:
  author: Orgtools
---

# Set up Orgtools

Orgtools is a company's decision record: who decided what, why, what was set aside, and the standing rules it keeps to. This skill connects the agent you are running in to that record, as the person you are talking with, so decisions made in a conversation reach the record and the record can be read from the conversation.

This is a Markdown instruction file, not a shell command. Read it and carry out the steps that apply. Account access, the MCP connection, and a verified whoami are three separate milestones. Report which are complete, and never say setup is done while one is pending.

Before anything else, look at the client's existing MCP configuration. If an `orgtools` server is already there and connected, skip to step 4 and prove it: a whoami answer means the account and the consent are already done, and a refusal tells you which one is not. Otherwise start at step 1 and take the steps in order. Do not skip step 4 in either case; a configured server that has never answered is not a connection.

## 1. Account

Ask the person whether they already have an Orgtools account. Everything in this step happens in their browser, not in the chat.

- Existing users sign in at https://orgtools.com/auth/login. A person who belongs to more than one organization picks one at sign-in; the consent screen in step 3 binds the connection to that one, so make sure it is the one they mean.
- New users register at https://orgtools.com/auth/register, verify their email address, and then name their company or team. That creates the organization, on a 30-day trial, that the connection will act in. There is no approval to wait for.

Never ask the person to paste a password, a one-time code, or a token into the conversation. The sign-in that matters for the connection happens in step 3, in the browser, and Orgtools never issues a key for you to hold. Do not create a second account or organization for a person who already has one; if they need access to an existing organization, its admin invites them from Settings.

## 2. Add the server

One MCP server, the same for every client. Add it once, and leave every other server in the client's configuration alone.

- Name: `orgtools`
- URL: `https://orgtools.com/mcp`
- Transport: Streamable HTTP
- Auth: OAuth, completed in the browser. No API key, no header, no secret.

Claude Code:

```
claude mcp add --transport http orgtools https://orgtools.com/mcp
```

Then run `/mcp` inside Claude Code, choose `orgtools`, and it opens the browser sign-in.

Codex CLI and the Codex app (they share one configuration):

```
codex mcp add orgtools --url https://orgtools.com/mcp
codex mcp login orgtools
```

Run the `add` yourself. The `login` opens a browser, so it runs in the person's own terminal, or as Authenticate under Settings, MCP servers in the Codex app; Codex's agent shell also has network access turned off by default, so do not run it from there. Tell the person to run it, then continue.

Any other client: add a remote (HTTP) MCP server named `orgtools` at `https://orgtools.com/mcp` with OAuth as the auth method, using that client's own command or settings screen. Check the client's documentation for the exact shape. Do not assume its config file matches another client's JSON, and do not invent a `headers` or `apiKey` field, because the server does not accept one.

If you cannot configure your own client, give the person the exact steps for theirs and pick this up again once the server is connected. If the client cannot do remote HTTP MCP with OAuth at all, say so and name one that can; do not substitute a key or token workaround, because there is none. If the server connects but its tools are not visible, reload the session.

The server registers clients itself, through OAuth Dynamic Client Registration or Client ID Metadata Documents, so there is no allow-list to get on and nothing to request from Orgtools first.

## 3. Consent

The browser sign-in lands on an Orgtools consent screen. It names three things:

1. The tool asking, identified by the host of its published client URL where the tool has one, or by its self-reported name where it does not.
2. The firm the tool will act in.
3. The seat the connection will show up as in Orgtools, named for the person and the tool, for example "Their Name · Claude Code".

The person clicks Allow. There is no workspace-selection step afterward: the seat is bound to that firm at consent, so if they want a different firm they switch it in Orgtools and consent again.

For a command-line client the screen also warns that the connection returns to the person's own computer and should only be approved if they started it themselves, just now. Tell them to expect that and to read it.

The seat appears on the person's Settings page in Orgtools and can be disconnected there at any time. Re-running consent for a tool that already has a seat reuses the seat; it does not mint a second one.

## 4. Prove it

Configuration alone is not proof. Once the client reports the server connected, call the `whoami` tool. It takes no arguments and needs no permissions. It answers with the person, the firm, and the seat, in this shape:

> You are {person} at {firm}, and this connection speaks as your Orgtools AI seat {seat} ({seat_ref}).

Report all three back to the person, verbatim, and say which client you did this from. If `whoami` does not answer, the connection is not made, whatever the client's status line says. Go back to step 2 and check the URL and the transport before anything else.

## Then

Discover the tools from the server rather than from this file, because the server is the authority on what it offers. As of this writing it exposes seven:

- `whoami`: who this connection acts as. Needs no permissions.
- `find_decisions`: the firm's decisions, newest first, as the person sees them, with an optional text query and status.
- `get_decision`: one decision in full: the question, the context, what was chosen and why, what was set aside and why, the constraints, who took part, and who decided.
- `list_signals`: the patterns and contradictions Orgtools has detected across the firm's facts, each with the decision it implies. Needs the knowledge-management permission.
- `log_decision`: record a decision the person has just made, in their words. The person is always the decider; you are recorded as how it arrived.
- `find_principles`: the firm's standing rules, with their kind, force, and rationale. Needs the knowledge-management permission.
- `log_principle`: log a standing rule the person just stated. Live at once if they hold attest authority; otherwise it waits for an admin.

Everything you read runs as the person: you see what they can see and nothing more. Everything you write is created by them, with your seat named as the source.

Not everything a person says is a decision for the record. Before `log_decision` writes, Orgtools checks the candidate against one bar: someone who has never opened the software could reasonably disagree with it, and it is about what the firm gets rather than how the work gets done. When a candidate misses, the tool refuses with a one-sentence reason and, where it can, a rewrite in the firm's own terms for the person to approve. Relay the reason; do not retry with the same words.

For the rest of what Orgtools is and does, read https://orgtools.com/llms.txt.

## References

- Orgtools for AI assistants, with per-client walkthroughs: https://orgtools.com/integrations/ai-assistants
- The MCP server: https://orgtools.com/mcp
- The site overview for agents: https://orgtools.com/llms.txt
- The agents page: https://orgtools.com/agents