# Minz.ai MCP connector — installation guide for agents

Server URL: `https://mcp-staging.minz.ai/mcp`
Catalog version: 1.9.0
Human guide: https://mcp-staging.minz.ai/docs

> This is a non-production deployment. The Claude plugin in the Minz repo is pinned to production (`https://mcp.minz.ai/mcp`); for this server use the `claude mcp add` / `codex mcp add` commands below with the URL above.

## Quick path

1. Decide which client the user is in (table below). If you are running inside Claude Code or Codex, you can do the install yourself.
2. Run the install command for that client.
3. Ask the user to sign in to Minz.ai in their browser (you cannot do this step).
4. Run the checks in "Verify" and report the result to the user in their language.

| The user is in | Who does it | Go to |
|---|---|---|
| Claude Code | You (agent) run the commands; the user signs in | "Claude Code (CLI)" |
| Codex CLI | You (agent) run the commands; the user signs in | "Codex CLI" |
| Claude web, desktop or mobile | The user, with your numbered steps | "Claude (web, desktop)" |
| ChatGPT | The user, with your numbered steps | "ChatGPT" |
| Wants the Minz skills as well (call prep, pipeline review, ...) | Install the connector first, then the plugin | "Plugins (optional skills)" |

Done means: the sign-in completed and a test question returned Minz.ai data. A command that exited 0 is not enough.

## What you are installing

- A remote MCP server over Streamable HTTP (`POST https://mcp-staging.minz.ai/mcp`). `GET` and `DELETE` on `/mcp` return 405 by design.
- Tools over the user's Minz.ai workspace: CRM, pipeline, calendar, tasks, activities, cases, OKRs and MinzSpend expenses. Read-only by default; write tools (chat messages, Drive files, tasks, calendar events, OKR drafts and check-ins, deal follow) appear only when the user approves their separate `.write` scope, and agents should confirm with the user before calling them.
- Authentication is OAuth 2.1 with discovery (RFC 9728 → `https://mcp-staging.minz.ai/.well-known/oauth-protected-resource/mcp`), dynamic client registration and PKCE S256. No client ID or secret is needed.
- Some tools also return interactive views (MCP Apps). Claude (web/desktop) and ChatGPT render them; CLI clients show the same data as text.

## Rules for agents

1. You can run the CLI steps (Claude Code, Codex). The OAuth consent always happens in the user's browser: tell the user to sign in to Minz.ai, pick the workspace and select **Allow access**. Never ask for their password.
2. You cannot click through claude.ai or chatgpt.com settings. For those, give the user the numbered steps below and wait for them to confirm.
3. Do not write access tokens into files in a repository. If the user gives you a bearer token for testing, keep it in an environment variable.
4. Answer the user in the language they write in. If a step fails, show them the exact error and use the Troubleshooting table; do not retry blindly more than once.
5. After installing, verify (section "Verify") before telling the user it works.

## Claude Code (CLI) — agent can run this

```sh
claude mcp add --transport http --scope user minz https://mcp-staging.minz.ai/mcp
```

Then, inside Claude Code, run `/mcp`, select **minz** and choose **Authenticate**. A browser window opens for the Minz.ai sign-in; the user approves it there. Check with `claude mcp list`; until the user authenticates, the server is listed as needing authentication. Use `--scope project` instead to share the entry through `.mcp.json` in a repository; the token itself is never written there.

## Codex CLI — agent can run this

```sh
codex mcp add minz --url https://mcp-staging.minz.ai/mcp
codex mcp login minz
```

`codex mcp add` writes the config and usually starts the OAuth sign-in right away: it opens the browser and **waits until the user finishes signing in**, so run it where the user can see the browser and tell them to approve. If it returns without signing in, run `codex mcp login minz`. Check with `codex mcp list`: the Auth column changes from "Not logged in" once the user has approved. The equivalent `~/.codex/config.toml` entry is:

```toml
[mcp_servers.minz]
url = "https://mcp-staging.minz.ai/mcp"
```

## Claude (web, desktop) — user does this

1. Open **Settings → Connectors** → **Add custom connector**. (Team/Enterprise: an organization owner adds it under organization settings first.)
2. Name: `Minz.ai`. URL: `https://mcp-staging.minz.ai/mcp`. Leave the OAuth client fields empty.
3. Select **Connect**, sign in to Minz.ai, choose the workspace, select **Allow access**.
4. In a chat, enable Minz.ai in the tools menu.

## ChatGPT — user does this

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.
2. Choose **Create**. Name: `Minz.ai`. MCP server URL: `https://mcp-staging.minz.ai/mcp`. Authentication: **OAuth** (no client ID/secret). Confirm and create.
3. Select **Connect**, sign in to Minz.ai, choose the workspace, select **Allow access**.
4. In a new chat, pick the app from the **+** menu.
5. After a server deploy, open the app settings and select **Refresh** so ChatGPT reloads the tool list.

## Plugins (optional skills)

The connector alone gives an assistant the tools. A plugin adds ready-made skills on top (call prep, pipeline review, my week, expense review and more). Plugins need the connector, so install and authenticate the connector first. Both plugins are read-only: they never call the write tools. They are published for production (`https://mcp.minz.ai/mcp`) only.

### Claude Code plugin — agent can run this

Skills: `call-prep`, `pipeline-review`, `my-week`, `expense-review`. The plugin also registers the production connector.

```sh
claude plugin marketplace add min-ai-bros/mcp   # private repo: needs GitHub access; or pass a local checkout path
claude plugin install minz-ai@minz
```

Then authenticate through `/mcp` (see "Claude Code (CLI)").

### ChatGPT / Codex plugin

Source: `chatgpt-plugin/minz-ai` in the min-ai-bros/mcp repository (version 0.2.0, manifest `.codex-plugin/plugin.json`). English is the default language; the assistant answers in the language the user writes in (Vietnamese questions get Vietnamese answers). It has 10 skills and covers the whole read-only tool catalog: `crm-assistant`, `work-overview`, `minzspend-tracker`, `deal-coaching`, `my-inbox`, `workspace-explorer`, `call-prep`, `pipeline-review`, `my-week`, `expense-review`.

- Install the connector first (the Codex CLI or ChatGPT section above), then add the plugin from the plugin directory of your client, or from a checkout of the repository if your client supports local plugins. Client menus change often: use the client's own plugin-install flow and do not invent commands.
- If the user's ChatGPT does not list Minz.ai in its plugin directory yet, the connector still works without the plugin; tell the user that skills are not installed and continue.

## Verify

Without credentials (any shell):

```sh
curl -s https://mcp-staging.minz.ai/healthz
curl -s https://mcp-staging.minz.ai/.well-known/oauth-protected-resource/mcp
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://mcp-staging.minz.ai/mcp   # expect 401 with a WWW-Authenticate header
```

After connecting, ask the assistant: "Summarize my sales pipeline" (tool `crm_pipeline_summary`) and "Find deals for Acme" (`crm_deals_search`). In Claude or ChatGPT these two show an interactive view; elsewhere they return text.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `OAuth failed: invalid_scope - Requested scope is not supported` | The client requested a scope the Minz.ai authorization server does not grant yet. The server only advertises grantable scopes; an old client registration can still carry the previous list. | Delete the connector/app and create it again, then connect. |
| 401 `invalid_token` after it worked | Access token expired or revoked, or the connection was unused for 30 days. | Reconnect (`/mcp` → Authenticate, `codex mcp login minz`, or Connect in the app settings). |
| Some tools are missing | The grant does not include their scope, or the scope is not enabled for the workspace yet. | Reconnect and approve the scopes; tools appear only for granted scopes. |
| Only text, no interactive view | The client does not render MCP Apps (CLI clients), or it cached the tool list from before the views existed. | Expected in CLIs. In ChatGPT select **Refresh**; in Claude remove and re-add the connector. |
| Sign-in page does not open | Pop-ups or trackers blocked. | Allow pop-ups for claude.ai / chatgpt.com and minz.ai, then retry. |
| 405 on `GET https://mcp-staging.minz.ai/mcp` | By design: the server only accepts POST. | Nothing to fix. |

## Tools and scopes

Tools are listed per call to `tools/list` and depend on the scopes granted to the connection.

| Tool | Title | Scope |
|---|---|---|
| `crm_deals_search` | Search CRM deals | `crm.deals.read` |
| `crm_contacts_search` | Search CRM contacts | `crm.contacts.read` |
| `crm_pipeline_summary` | Summarize sales pipeline | `crm.pipeline.read` |
| `crm_deals_history` | Get deal history | `crm.deals.read` |
| `crm_leads_search` | Search CRM leads | `crm.leads.read` |
| `crm_accounts_search` | Search CRM accounts | `crm.accounts.read` |
| `general_calendar_search` | Search calendar events | `general.calendar.read` |
| `general_tasks_search` | Search tasks | `general.tasks.read` |
| `general_activities_search` | Search activities | `general.activities.read` |
| `general_notes_search` | Search notes | `general.notes.read` |
| `general_approvals_search` | Search approvals | `general.approvals.read` |
| `general_requests_search` | Search my requests | `general.requests.read` |
| `general_notifications_search` | Search notifications | `general.notifications.read` |
| `finance_expenses_search` | Search expenses | `finance.expenses.read` |
| `finance_reports_search` | Search expense reports | `finance.reports.read` |
| `crm_notes_search` | Search CRM notes | `crm.notes.read` |
| `crm_products_search` | Search CRM products | `crm.products.read` |
| `crm_contracts_search` | Search sales contracts | `crm.contracts.read` |
| `crm_pipelines_list` | List sales pipelines | `crm.pipelines.read` |
| `crm_pipeline_health` | Check pipeline health | `crm.pipeline.read` |
| `crm_team_search` | Search team members | `crm.team.read` |
| `crm_quotes_search` | Search CRM quotes | `crm.quotes.read` |
| `crm_kpi_progress` | Read KPI progress | `crm.kpi.read` |
| `crm_deals_win_patterns` | Analyze win patterns | `crm.insights.read` |
| `crm_deals_lookalike` | Find lookalike deals | `crm.insights.read` |
| `crm_meetings_last` | Read last meeting | `crm.meetings.read` |
| `crm_care_search` | Search care tickets | `crm.care.read` |
| `ops_cases_search` | Search cases | `ops.cases.read` |
| `ops_cases_detail` | Get case detail | `ops.cases.read` |
| `ops_workflow_instances_search` | Search workflow instances | `ops.workflows.read` |
| `ops_workflow_tasks_search` | Search workflow tasks | `ops.workflows.read` |
| `ops_workflow_definitions_search` | Search workflow definitions | `ops.workflows.read` |
| `ops_sla_summary` | Summarize SLA | `ops.sla.read` |
| `company_org_nodes_search` | Search org nodes | `company.orgchart.read` |
| `company_org_edges_search` | Search org relations | `company.orgchart.read` |
| `company_profile_get` | Get company profile | `company.profile.read` |
| `company_people_search` | Search people directory | `company.people.read` |
| `company_assignments_search` | Search position assignments | `company.people.read` |
| `omni_conversations_search` | Search conversations | `omni.conversations.read` |
| `omni_conversations_detail` | Get conversation detail | `omni.conversations.read` |
| `omni_channels_list` | List channels | `omni.channels.read` |
| `omni_inboxes_list` | List inboxes | `omni.inboxes.read` |
| `chat_conversations_search` | Find team chat conversations | `chat.conversations.read` |
| `chat_members_list` | List chat members | `chat.conversations.read` |
| `chat_messages_send` | Send team chat message | `chat.messages.write` |
| `chat_jarmin_ask` | Ask Jarmin in team chat | `chat.messages.write`, `chat.jarmin.write` |
| `drive_files_create` | Save file to Drive | `drive.files.write` |
| `drive_files_upload_start` | Start a file upload | `drive.files.write` |
| `drive_files_upload_finish` | Finish a file upload | `drive.files.write` |
| `general_calendar_create_event` | Create calendar event | `general.calendar.write` |
| `general_calendar_update_event` | Update calendar event | `general.calendar.write` |
| `general_calendar_delete_event` | Delete calendar event | `general.calendar.write` |
| `general_calendar_respond_event` | Respond to calendar invitation | `general.calendar.write` |
| `okr_context_get` | Load OKR context | `okr.objectives.read` |
| `okr_quality_review` | Review OKR quality | `okr.objectives.read` |
| `okr_objectives_draft` | Draft OKR objective | `okr.objectives.write` |
| `okr_key_results_checkin` | Check in key result | `okr.key_results.write` |
| `general_tasks_create` | Create task | `general.tasks.write` |
| `general_tasks_update` | Update task | `general.tasks.write` |
| `crm_deals_follow` | Follow deal for Claude | `crm.deals.follow.write` |
| `docs_register_search` | Search document register | `docs.register.read` |
| `docs_numbers_explain` | Explain document number | `docs.register.read` |
| `docs_books_list` | List document books | `docs.register.read` |
| `docs_templates_search` | Search document templates | `docs.templates.read` |
| `docs_acknowledgements_pending` | List pending acknowledgements | `docs.acknowledgements.read` |

Support: support@minz.ai