# Local development and testing

Source: https://www.supervisible.com/developers/mcp/local-testing

Test the local MCP directly with Codex or Claude Code, then verify hosted clients separately.


This guide is for contributors running the Supervisible application. Use a disposable database with synthetic data. Confirm both the application and migration connections point to that database before running setup or write tests. Never assume a local web server implies a local database.

## Connect a local client

With the app running at `http://localhost:3000`, configure a separate development connection:

```bash
codex mcp add supervisible-local --url http://localhost:3000/api/mcp
codex mcp login supervisible-local
```

Or use Claude Code:

```bash
claude mcp add --transport http supervisible-local http://localhost:3000/api/mcp
```

In Claude Code, open `/mcp` and authenticate. In either client, complete sign-in and workspace consent, then call `whoami`. The app's configured origin and OAuth metadata must match the development URL. Use your actual port consistently.

No tunnel is needed when the client and app run on the same machine. A client running in a container, remote development host or cloud has a different network context. Claude's hosted custom connectors connect from its cloud infrastructure; ChatGPT also needs an endpoint it can reach. Use a properly configured HTTPS development endpoint or supported tunnel for those tests, then reconnect using its URL. See [Claude's connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) and [OpenAI's connection guide](https://developers.openai.com/plugins/quickstart).

## Acceptance checks

Use two workspaces and at least an admin, an ordinary member and a freelancer. Seed people, a project, assignments, compensation periods and leave.

1. Complete actual OAuth sign-in, workspace selection and tool discovery.
2. Run `whoami` and read a known record. Confirm a foreign-workspace ID is unavailable.
3. Exercise an allowed write as a preview. Verify that no record changed. Apply deliberately and read it back.
4. Repeat with a member who lacks permission. Verify denial or appropriate field redaction.
5. Change the connected member's permissions and repeat the request without relying on an old session snapshot.
6. Change web workspaces and confirm the existing grant stays bound to the original membership.
7. Test ambiguous names, invalid fields, stale revisions and partial import results.
8. Revoke the connection and verify it stops working. Check configured notification/calendar effects separately when testing writes that cause them.

## Repository checks

From `apps/app`, after verifying test database configuration:

```bash
pnpm test:setup
pnpm test:unit
pnpm test:integration
pnpm check-types
pnpm lint
```

From the repository root, `pnpm signoff:local` runs the full local gate, including browser tests and the runtime-log audit. Review its report in `test-results/local-signoff`. Use isolated test credentials; do not include them in docs or screenshots.

Local acceptance is evidence for that build and environment. It does not establish hosted-client compatibility or directory approval. Use the [reviewer guide](https://www.supervisible.com/developers/mcp/store-readiness.md) for the remaining hosted checks.