> For the complete documentation index, see [llms.txt](https://docs.themochi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themochi.app/common-tasks/connect-ai-agent.md).

# Connect an AI agent

An **AI agent** is a tool that can use commands or connected apps for you. Choose the connection based on where the agent runs. The agent must never receive, read, paste, print, or store a Mochi credential.

After choosing a connection, use the [generated OpenAPI contract](https://openapi.gitbook.com/o/M0sgy6xKutCblHRqGmE5/spec/mochi-api.json) for current authentication requirements and exact operation details.

## Choose a connection

| Workload                                           | Use                          | Credential boundary                                                                                                                                  |
| -------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Interactive agent or developer on a local computer | Mochi CLI OAuth              | `mochi auth login` opens Mochi in the browser and stores the approved connection in the OS keychain. The agent sees only structured command results. |
| Scheduled job, CI runner, or unattended server     | Organization-scoped API key  | An operator creates a key with only the needed permissions. The workload reads it from a server-side secret manager.                                 |
| Agent already connected through Mochi MCP          | Existing MCP connection      | Keep using that connection. Do not export, exchange, or convert its credential.                                                                      |
| Third-party browser application                    | Registered OAuth application | The application sends the user to Mochi for approval and manages its own redirect and refresh flow.                                                  |

OAuth is browser-based approval. MCP is the connection standard used by some AI tools. An existing Mochi browser session makes approval smoother because the customer may not need to enter a password again. It does not skip consent: the customer still chooses the organization and approves the requested Public API scopes.

## Optional: give the agent the Mochi skill

Install the high-level skill from the public CLI repository:

```bash
npx skills add TheMochiApp/mochi-cli --skill mochi-api
```

The skill teaches the agent to read `/llms.txt`, choose the smallest current task guide, and inspect OpenAPI for exact request details. It does not contain a copied endpoint reference or credentials. Skill installation is separate from publishing the `@themochiapp/cli` npm package.

## Connect on a trusted local computer

Use this path only when the agent and customer share a trusted local computer and Mochi has enabled Public API OAuth for that organization. The Mochi CLI is a command-line tool for making approved, read-only requests.

1. Install the Mochi CLI from its [canonical repository](https://github.com/TheMochiApp/mochi-cli) using the currently published release instructions.
2. Inspect the installed command surface with `mochi --help`.
3. Run `mochi auth login`, request only the read scopes needed for the task, and complete organization/scope approval in the browser.
4. Check non-secret state with `mochi auth status`.
5. Run a read command and parse its single JSON result. Branch on `ok`; do not scrape human output.
6. Remove the approved connection with `mochi auth logout` when it is no longer needed.

The CLI is intentionally read-only. For a write integration, read the relevant task guide and current OpenAPI contract. Write a specific plan and use a separately approved direct API integration. Never invent a write-oriented `mochi` command.

## Connect a scheduled job or server

Use an API key for a scheduled job, CI runner, hosted agent, or server process:

1. Name the exact job and organization.
2. Request only the scopes used by that job.
3. Store the key in the platform secret manager and inject it at runtime.
4. Keep it out of prompts, command arguments, source control, logs, screenshots, browser code, and support messages.
5. Verify the first request is read-only and organization-bound before enabling a schedule.
6. Use separate keys for separate integrations so one workload can be rotated or revoked independently.

See [Choose how to authenticate](/start-here/authentication.md) for key replacement and identity rules. See [Choose permissions](/start-here/scopes.md) for the current scope list.

## Keep an existing MCP connection

If the customer already connected Mochi through MCP, continue through that connection. Installing the skill does not require another browser sign-in. The skill may help the agent find public documentation, but it must not ask to reveal an MCP token or assume that MCP supports every Public API operation.

## Confirm the connection safely

A successful setup proves only the intended boundary:

* the selected organization is correct;
* the granted scopes match the task;
* a read returns structured data;
* a disallowed scope or cross-organization resource is denied; and
* no authorization header, token, API key, contact value, or customer payload appears in agent context or logs.

If documentation, OpenAPI, installed CLI help, and observed behavior disagree, stop and record the sanitized `X-Request-ID`, status, method, path, and UTC time. Do not troubleshoot by printing the credential.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.themochi.app/common-tasks/connect-ai-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.