# ObjectStack plugin for Claude Code

Connect Claude Code to **any ObjectStack deployment** — cloud or self-hosted — over the
Model Context Protocol. Discover objects, query and change records, and run business
actions, all under **your own permissions and row-level security**.

One plugin serves every deployment: the deployment URL is the only per-environment
input. Identity is self-serve — every ObjectStack deployment is its own OAuth 2.1
authorization server with Dynamic Client Registration, so connecting just opens a
browser login. No admin-minted credentials, nothing to paste into config files.

## Install

```bash
claude plugin marketplace add objectstack-ai/claude-plugin
claude plugin install objectstack@objectstack
```

## Connect

**Guided (recommended):** run `/objectstack:connect` and follow along — it asks for
your deployment URL, registers the MCP server, and verifies the connection. Find your
URL on your deployment's **Setup → Connect an agent** page, or just use the address
you open in the browser.

**One-liner:**

```bash
claude mcp add --transport http objectstack https://<your-deployment>/api/v1/mcp
```

**Fixed environment via env var:** the plugin ships an MCP server bound to
`${OBJECTSTACK_MCP_URL}` — set it once (shell profile or project `.claude/settings.json`
`env`) and the server is live without any `claude mcp add`:

```bash
export OBJECTSTACK_MCP_URL="https://acme.objectos.app/api/v1/mcp"
```

**Headless (CI, machine accounts):** use an ObjectStack API key instead of OAuth:

```bash
claude mcp add --transport http objectstack https://<your-deployment>/api/v1/mcp \
  --header "x-api-key: <key>"
```

## What's inside

| Piece | Purpose |
| --- | --- |
| `skills/objectstack/SKILL.md` | The portable ObjectStack agent skill: teaches discover-first workflow (`list_objects` → `describe_object` → act), the full tool surface incl. business actions (`list_actions`/`run_action`), and governance conventions (permissions/RLS are expected behavior, prefer actions over hand-edits, confirm destructive steps) |
| `.mcp.json` | MCP server bound to `${OBJECTSTACK_MCP_URL}` |
| `commands/connect.md` | `/objectstack:connect` guided setup |

The skill enumerates **no schema** — objects and actions are discovered live from your
deployment, so one install keeps working as your apps evolve, and works against every
environment your account can reach.

## Notes

- Requires the deployment's MCP surface, which is **on by default** (ObjectStack ≥ 13);
  an operator can opt out with `OS_MCP_SERVER_ENABLED=false`.
- Intranet deployments work from local clients like Claude Code (OAuth 2.1 TLS rule:
  https required, loopback exempt — internal CAs are fine if your OS trusts them).
- `SKILL.md` is a copy of the single source in
  [`@objectstack/mcp`](https://www.npmjs.com/package/@objectstack/mcp)
  (`renderSkillMarkdown()`); CI fails on drift. Re-render with `npm run sync:skill` —
  never hand-edit.

## License

Apache-2.0 — see [LICENSE](LICENSE).