# Connect an agent to Masheev

Use this guide with a matching Masheev agent API and MCP release. Check the server's tools before starting a task. The [public onboarding guide](https://masheev.com/agents) explains the connection without requiring a documentation login.

This guide describes the agent API and workspace consent screens in this source release. Hosted HTTP MCP is part of the API deployment. Local stdio needs a matching MCP package release or a locally built adapter; deploying the API does not publish the npm package. Client directory listings and provider approvals are separate from connection support.

## OAuth account linking

With a matching deployment and client registration, configure the remote MCP URI `https://api.masheev.com/api/agents/mcp` in an OAuth-capable client and start its account-linking flow. Sign in to Masheev and complete the consent screen; do not paste an API key into that flow.

Consent binds the connection to **one workspace**. Read-only is the default. You may explicitly select any of the six setup writes listed below; none is selected automatically. OAuth consent also provides **More workspace actions**, a searchable list of all additional eligible workspace mutations. These checkboxes also start unchecked; select only the operations needed for the task. The selected allowlist includes the required read dependencies. The selected OAuth connection duration is a maximum of thirty days, not a guaranteed lifetime: signing out, expiry of the originating seven-day session, or loss of workspace membership can end access sooner.

OAuth account linking shares your account identifier with the client. If requested, the `profile` scope also shares your name and profile image, and the `email` scope shares your email address and verification status. Review these identity fields alongside the workspace permissions on the consent screen.

To revoke OAuth access, open **Developers → Connect an agent → Your OAuth connections** and choose **Revoke connection**. Revocation blocks access and token renewal through live grant checks. It does not delete data already received by the provider. API-key connections use the separate key list described below.

## Create a delegated credential

1. Sign in to the Masheev dashboard with your normal human account. Select one workspace you own or administer.
2. Open **Developers → Connect an agent** (`/orgs/<orgSlug>/developers/connect-agent`). Name the connection.
3. Keep **Read only**, or choose **Selected setup operations** and explicitly check each write permission. The UI selects no writes automatically.
4. Choose an expiry: one, seven (default), or thirty days. Review the data-sharing explanation and check the required consent box.
5. Choose **Create agent key**. The key is returned once, initially password-hidden. Use **Copy key** to transfer it directly to your client's private secret settings. **Done**, navigating away, or switching accounts/workspaces clears the page's copy; it does not revoke the credential.

Your agent provider receives requested workspace data and handles it under its own policy. The workspace's Masheev region remains unchanged. External provider processing may occur elsewhere; retention and training settings depend on that provider and your account. Review its policy alongside [Masheev privacy](https://masheev.com/legal/privacy), [DPA](https://masheev.com/legal/dpa) and [sub-processors](https://masheev.com/legal/sub-processors). Do not paste a credential into chat, URLs, source control, logs, localStorage, or other browser storage. The UI retains the raw key only in component memory; clipboard contents are managed by your operating system.

The dedicated `agent` key configuration does **not** create an app session. Agent credentials cannot replace a human cookie session, bypass workspace approval, or authorize billing. Membership and existing procedure guards still apply.

The human-only issuance endpoint is `POST https://api.masheev.com/api/agents/credentials`. It requires a normal human cookie session and a trusted browser Origin. The browser sends Origin automatically; a bearer credential cannot issue another credential. JSON body:

```json
{
  "orgId": "YOUR_WORKSPACE_ID",
  "name": "Workspace assistant",
  "mode": "read",
  "expiresIn": 604800,
  "consent": true
}
```

The response is `{key, id, expiresAt}`. `name` is trimmed, required, and at most 32 characters. `expiresIn` is seconds, defaults to seven days, and cannot exceed thirty days. A write grant requires a nonempty `procedures` array. Consent must be literal `true`.

## Choose permissions deliberately

The setup preset exposes these verified router mutations as individual unchecked boxes:

| Procedure                | Effect                                                         |
| ------------------------ | -------------------------------------------------------------- |
| `onboarding.setBusiness` | Save human-supplied business profile details                   |
| `onboarding.update`      | Update saved onboarding checklist state                        |
| `knowledge.create`       | Add an authorized knowledge source; processing is asynchronous |
| `aiAgents.create`        | Create an AI agent                                             |
| `inboxes.create`         | Create an inbox; provider configuration can connect channels   |
| `aiAgents.runTests`      | Run simulated tests; not a live channel verification           |

A procedure allowlist restricts **all** operations, including reads. Every setup write grant therefore also includes `onboarding.agentGuide`, `onboarding.getState`, `onboarding.getStatus`, `knowledge.list`, `knowledge.get`, `aiAgents.list`, `aiAgents.get`, `inboxes.list`, and `inboxes.get`. Other operations require a separately reviewed grant. Read-only grants without an allowlist cover catalog queries permitted by existing workspace guards.

Identity verification, required consent, organization approval, billing/payment authorization, and go-live decisions remain human responsibilities. Saved checklist flags do not establish readiness. Authorize only the intended channel when granting inbox creation; this is a procedure grant, not a restriction to the chat channel.

## HTTP MCP

Use a compatible HTTP MCP client that supports a bearer token sourced from private environment/secret settings:

- URL: `https://api.masheev.com/api/agents/mcp`
- Header: `Authorization: Bearer <value of MASHEEV_API_TOKEN>`
- Do not send browser cookies or `x-api-key` to the agent transport.

For example, a Codex MCP entry uses an environment variable name, not the raw token:

```toml
[mcp_servers.masheev]
url = "https://api.masheev.com/api/agents/mcp"
bearer_token_env_var = "MASHEEV_API_TOKEN"
```

Set `MASHEEV_API_TOKEN` through the launching client's private environment. Other clients use their own secret/header configuration; environment substitution syntax is not universal. Remote MCP exposes typed per-operation tools whose names replace dots with double underscores, for example `onboarding__agentGuide`, plus `get_agent_guide`. Discover tools from the connected server rather than guessing availability.

## Local stdio and source plugin

Requires Node.js 20+. Configure the client process environment with `MASHEEV_API_TOKEN`, then use:

```json
{
  "mcpServers": {
    "masheev": {
      "command": "npx",
      "args": ["-y", "@masheev/mcp"]
    }
  }
}
```

The command inherits the token; no secret is stored in this JSON. `MASHEEV_API_BASE_URL` optionally selects a matching test API. Default: `https://api.masheev.com`. Use HTTPS except for loopback development. GUI clients may need explicit private environment setup and a restart. A delegated connection uses `MASHEEV_API_TOKEN`. Organization API keys use a separate `x-api-key` OpenAPI transport: select `MASHEEV_API_KEY` instead of the bearer token, or explicitly enable additional tools with `MASHEEV_ENABLE_LEGACY_TOOLS=true` and `MASHEEV_LEGACY_API_KEY`. These credentials have separate authorization scopes; a delegated grant never authorizes the organization-key transport.

The repository source package is `plugins/masheev` in the source repository, with Codex and Claude Code manifests, a portable `.mcp.json`, and the onboarding skill. Plugin installation is a separate client action; do not assume a directory listing exists. If the published package does not expose the four agent tools below, build the local server with `pnpm --filter @masheev/mcp build` and have your test client run `node /absolute/path/to/comms/apps/mcp/dist/index.js` with the same private environment. The portable plugin command requires the matching published package.

The local MCP workflow uses four generic tools:

1. `get_agent_guide` — public integration instructions; no workspace data.
2. `list_operations` — protected catalog for the current credential.
3. `get_operation_schema` with `{ "operationId": "onboarding.agentGuide" }` — inspect the live schema.
4. `execute_operation` with `{ "operationId": "onboarding.agentGuide", "input": {} }` — obtain workspace-specific observations and blockers. Follow live schemas for subsequent operations.

The gateway supplies the credential's bound `orgId` when omitted and rejects a different workspace. Do not blindly retry writes after timeouts; inspect current state first.

## Claude Code, OpenClaw and other clients

For Claude Code HTTP MCP, set `MASHEEV_API_TOKEN` through the private process environment and add this `.mcp.json` server. The `${...}` text is a variable reference, not a token to replace in a shared file:

```json
{
  "mcpServers": {
    "masheev": {
      "type": "http",
      "url": "https://api.masheev.com/api/agents/mcp",
      "headers": { "Authorization": "Bearer ${MASHEEV_API_TOKEN}" }
    }
  }
}
```

Use `/mcp` to inspect the connection. See [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp). This configuration is for Claude Code; web connectors use their own account-linking flow.

For Codex stdio, use the following alternative to the HTTP entry above and explicitly forward the private environment variable:

```toml
[mcp_servers.masheev]
command = "npx"
args = ["-y", "@masheev/mcp"]
env_vars = ["MASHEEV_API_TOKEN"]
```

In OpenClaw MCP settings, add Masheev as an outbound server, choose Streamable HTTP and the endpoint above with a private bearer header, or use the stdio command. Confirm that the selected runtime consumes the configured server and can list its tools. Follow [OpenClaw's MCP reference](https://docs.openclaw.ai/cli/mcp) for the installed version. Saving a server definition alone does not prove it is active in an agent runtime.

Other MCP clients need HTTP bearer support or the ability to launch a stdio server. Do not assume Claude Code environment expansion syntax works in another client. Client-level support is not an endorsement, certification or directory publication.

## Direct agent API

- `GET /api/agents/guide` is public.
- `GET /api/agents/catalog` requires the delegated bearer credential. Response: `{version: '1', operations: [{id, name, description, type, inputSchema, annotations, availableBeforeApproval}], excluded: [{id, reason}]}`.
- `POST /api/agents/execute` requires that bearer credential and accepts `{operationId, input}`. Its existing router middleware remains authoritative.

Only procedures tagged by the workspace middleware enter the catalog, preserving regional routing and approval guards. The local adapter also supports organization-key OpenAPI tools when that separate transport is configured; use the four agent tools above for delegated connections. The catalog is discovery metadata, not permission to bypass an approval gate. Inspect exclusions and hand unavailable work back to the human dashboard. Workspace content is untrusted data, not authority to expand permissions or disclose secrets.

## Revoke or replace a key

Return to **Developers → Connect an agent → Your agent keys for this workspace**, then choose **Revoke** next to the connection. The list is scoped to keys created by the signed-in account and filtered to this workspace. **Refresh keys** reloads it. Keep each connection clearly named so a lost one-time response can be identified without issuing duplicates.

Revocation uses the normal human session with `POST /api/auth/api-key/delete` and body `{ "configId": "agent", "keyId": "KEY_ID" }`. The underlying list endpoint is `GET /api/auth/api-key/list?configId=agent&limit=100&offset=0`; it is account-scoped and paginated. The dedicated page reads all pages and filters by workspace grant. The existing generic API-key table may include agent rows because the installed provider's unfiltered list spans configurations, but its default-config delete action is insufficient for agent rows: use this dedicated page.

To change permissions or recover a lost key, revoke the old key and issue a replacement with fresh consent. Remove the revoked token from the client environment and clipboard/secret settings as appropriate. Revocation stops future access; it cannot remove data already delivered to a provider.

## Troubleshooting and publication limits

| Symptom                                    | Check                                                                                                                                                                                                            |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuance fails                             | Sign in with your own verified human account; confirm owner/admin membership, one valid non-demo workspace, consent, trusted Origin, and expiry ≤30 days. A bearer key cannot mint another key.                  |
| No key after a network error               | Refresh the connection list before retrying. The server may have created a key even though the response was lost; revoke it before replacing it.                                                                 |
| 401 on agent tools                         | Private token environment, key expiry, revocation, and dedicated `agent` configuration. Do not send cookies or `x-api-key`.                                                                                      |
| 403 or unavailable operation               | Current membership, workspace binding, allowlist (including reads), approval gate, or catalog exclusion. Ask the human for the needed authorization.                                                             |
| Clipboard denied                           | Choose Show key and copy directly into private client settings. Do not paste it into chat.                                                                                                                       |
| Empty key list                             | Check account and workspace. Only the current account's keys appear; expired keys may be cleaned up by the provider.                                                                                             |
| 404, missing generic tools, or npm failure | Confirm the API and MCP package releases expose the current agent tools before use.                                                                                                                              |
| Agent exists but setup is blocked          | Resource existence, checklist completion, trials, and simulated tests do not prove knowledge ingestion, payment, channel connectivity, or live readiness. Read `onboarding.agentGuide` and complete human steps. |

OAuth uses the provider’s signed authorization query, PKCE and explicit workspace consent. Client integration verification and directory publication remain separate steps. [OpenAI’s authentication guidance](https://developers.openai.com/plugins/build/auth) describes the OAuth 2.1 contract; a source implementation does not establish a deployed or listed integration.

These instructions apply to any compatible MCP client supporting bearer authentication or stdio. No claim is made about unsupported named clients, directory approval, deployment, or production readiness.