> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents, models, and setup tools

> MCP tools for agents, model providers, Oqoqo AI defaults, MCP tool checks, setup links, and Ask Oqo in GitHub.

Manage agents, [custom agents](https://docs.oqoqo.ai/setup/custom-agents.md) (private beta), model lists, [Oqoqo AI defaults](https://docs.oqoqo.ai/setup/oqoqo-ai.md), MCP server authentication, dashboard setup links, and the GitHub accounts and repositories of [Ask Oqo in GitHub (CI/CD)](https://docs.oqoqo.ai/operate/ask-oqo-in-github.md) (private beta). Secrets stay in the dashboard ([Secrets stay in the dashboard](https://docs.oqoqo.ai/mcp-server/overview.md#secrets-stay-in-the-dashboard)).

* **Badges** are explained under [Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals).
* **`project_id`** is optional on most tools; without it, the server picks a project for that call only ([Projects](https://docs.oqoqo.ai/mcp-server/overview.md#projects)).
* **`expected_organization_id`** is an optional string on every write tool, omitted from parameter tables; pass `organization.id` from [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) ([Organization check](https://docs.oqoqo.ai/mcp-server/overview.md#organization-check)).
* **`limit`** values above a tool's maximum are capped, not refused.

## Tools

### inspect\_project\_ai

**Get built-in and custom agents, models, and Oqoqo AI settings.** Returns agents, provider and model readiness, your personal connections, model refresh state, and each Oqoqo AI feature's model and whether it can run. It never returns secrets or starts a refresh.

Read-only · CLI: [`oqoqo project ai inspect`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-inspect)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `view` | `roles`, `providers`, `agents`, `models`, `agent_registry` | No | What to list. Defaults to `roles`. |
| `provider_connection_id` | string | With `models`, unless `agent_key` is set | An `aic_` connection from the `providers` view. |
| `agent_key` | string | No | With `models`: a custom agent's `acp-` key, instead of `provider_connection_id`. |
| `query` | string | No | With `agent_registry`: match the registry ID, name, or description. Up to 200 characters. |
| `access` | `shared`, `private` | No | With `providers`: the organization's API-key connections, or your own accounts. |
| `connection_state` | `connected`, `needs_attention`, `not_connected` | No | With `providers`: only this state. `needs_attention` is saved but must be fixed, such as by signing in again. |
| `availability` | `available`, `unavailable` | No | With `models` and `provider_connection_id`: `available` lists the models that an agent or an Oqoqo AI feature can use now, and `unavailable` lists the rest. |
| `limit` | integer | No | Results per page, up to 500 (default 100). |
| `cursor` | string | No | The exact `nextCursor` from the previous page. Omit it on the first page. |

| `view` | Use it for |
| - | - |
| `roles` | The model for each Oqoqo AI feature, with `availabilityReason` and `availabilityMessage` when it cannot run, and the custom instructions |
| `agents` | Whether each agent is on, and its kind (`built_in` or `custom`). A built-in agent has `supportedProviders`: every provider type it works with (`templateKey`, `name`), in the order Oqoqo suggests them. The `providers` view items with the same `templateKey` say which ones work and give their `setupUrl`. |
| `models` | A provider's models, each with `availability` and, when it cannot be used, `availabilityReason` and `availabilityMessage`. Or a custom agent's models (**Agent default** first, then each model with the agent's own name; `agentState` is `current`, `stale`, or `unavailable`) |
| `providers` | Each provider's access (shared or private), `connectionState`, and model counts (`modelCount`, `enabledModelCount`, `unavailableModelCount`) |
| `agent_registry` | ACP Registry agents to create a custom agent from, with the environment variables each one usually reads |

**Result fields**

The `roles`, `providers`, `agents`, and `models` views return top-level `revision` (the project revision), `organizationRevision`, `secretRevision`, and `editRevision` fields for writes, plus agent, provider, model, and role counts, provider readiness, model refresh counts, and `blockers`. `blockers` is empty when you can run models; otherwise it says why not, with the dashboard `setupUrl` where a person fixes it.

A custom agent's `custom` block has `status` (`needs_values`, `testing`, `needs_attention`, `not_tested`, or `ready`), `description`, `revision`, `connectionId`, `url`, `definition`, `env`, `envNote`, `testBlockers`, `handshake` (start-up details such as `failure.message`, `failure.detail`, and `authMethods`), `fix` (the failed step and what to change), `mcpServersRefused`, and `latestRun`. See [Custom agent fields](https://docs.oqoqo.ai/cli/agents-and-models.md#custom-agent-fields).

In the `providers` view, each provider's `modelRefresh` has `status`, `listedAt`, and the counts of the last refresh. `listedAt` is set when the refresh has read the provider's list, so the `models` view has those models while `status` is still `running`. See [`oqoqo project ai inspect`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-inspect).

A provider's `modelCount` counts the models that an agent or an Oqoqo AI feature can use now, and `enabledModelCount` counts the ones of those that are turned on. `unavailableModelCount` counts the listed models that cannot be used with the current credentials.

In the `models` view of a provider, each model has `availability` (`available` or `unavailable`). An unavailable model also has `availabilityReason` (`refused`, `credentials_changed`, or `not_checked`) and `availabilityMessage`, which says the reason in a sentence. [Models that cannot be used](https://docs.oqoqo.ai/setup/model-providers.md#models-that-cannot-be-used) explains each reason. `availability` with another view or with `agent_key` returns `invalid_request`.

A cursor continues only the list it came from, so pass the same `availability` with it. A cursor returns `stale_cursor` when the configuration changed between pages, usually from a model refresh.

### manage\_project\_ai

**Create custom agents and change agents, models, and Oqoqo AI settings.** Creates or changes custom agents, turns agents and models on or off, refreshes model lists, states context windows, and sets each Oqoqo AI feature's model and instructions. No operation carries a secret.

Changes data · CLI: [`oqoqo project ai apply`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-apply)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `operation` | object | Yes | One change, chosen by `action`, as below. |

| `action` | Fields | What it does |
| - | - | - |
| `set_agents` | `expectedRevision`, and either `agents` (1 to 1,000 items, each `key` and `enabled`) or `enabled` (never both) | Turns agents on or off. Send `enabled` without `agents` for every agent. |
| `set_roles` | `expectedOrganizationRevision`, `roleBindings` | Sets each Oqoqo AI feature's model. A binding has `role` (`ask`, `judge`, `sweep`, `consolidation`), nullable `providerConnectionId`, `providerModelId`, and `effortLevel` (always include these three keys), optional `preserveUnavailable`, and optional `customInstructions`. To keep a saved model that can't run, send `preserveUnavailable` with `null` IDs. |
| `set_model_enabled` | `connectionId`, `modelId`, `enabled` | Turns one model on or off. For a custom agent, use its `custom.connectionId`. |
| `set_models_enabled` | `connectionId`, `enabled`, optional `modelIds` (1 to 5,000 IDs) | Turns a connection's models on or off, all of them without `modelIds`. |
| `set_model_context_windows` | `connectionId`, `models` (1 to 5,000 entries, each `modelId` and `contextWindowTokens` from 1 to 2,147,483,647, or `null` to clear) | States context windows on an organization connection. The provider's current window wins. |
| `refresh_models` | optional `connectionIds` (1 to 200 IDs) | Queues refreshes for these connections, or all you can refresh. Poll `inspect_project_ai`. |
| `create_custom_agent` | `name` (up to 120 characters), `source`, optional `description`, `env`, `skillsFolder` | Creates a custom agent (private beta). |
| `update_custom_agent` | `agentKey`, `expectedRevision`, and any of `name`, `source`, `description`, `env`, `skillsFolder` | Changes a custom agent. Send a new `source` to change how it installs. |

A custom agent's `source` is one of:

* `kind: "registry"` with `registryId` and an optional `version`: an agent from the ACP Registry.
* `kind: "manual"` with `install` and optional `args`. `install` is an npm package (`kind: "npm"`, `package`), a Python package (`kind: "python"`, `package`), or a download (`kind: "download"`, `url`, `sha256`, `command`).
* `kind: "agent_json"` with `agentJson`: an `agent.json` definition.

`env` lists up to 64 environment variable names. Values are entered only in the dashboard, and the result returns the agent's page and the dashboard link for each value. `skillsFolder` is the folder where the agent reads skills, up to 256 characters.

A stale revision changes nothing and returns `configuration_changed`, with `details.currentRevision` when the target has one. An invalid operation returns `validation_error`. Read `inspect_project_ai` again before you retry. When a public catalog lists a context window for a model, `inspect_project_ai` reports it as `suggestedContextWindow`, which applies only after you state it. Connecting, signing in again, switching accounts, and entering credentials stay on the provider's dashboard link from `inspect_project_ai`.

### delete\_project\_ai

**Remove custom agents or provider connections.** Removes a custom agent, deletes a custom provider connection, resets a built-in organization connection, or disconnects your personal provider account.

Destructive · CLI: [`oqoqo project ai delete`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-delete)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `operation` | object | Yes | One removal, chosen by `action`, as below. |

| `action` | Fields |
| - | - |
| `remove_custom_agent` | `agentKey`, `expectedRevision` |
| `delete_connection` | `connectionId`, `expectedOrganizationRevision`, `expectedSecretRevision`, `expectedEditRevision` |
| `reset_connection` | `connectionId`, `expectedOrganizationRevision`, `expectedSecretRevision`, `expectedEditRevision` |
| `disconnect_personal_connection` | `connectionId` |

A removed custom agent no longer shows in new experiments or the Agents list, and Oqoqo clears its environment variable values. Past results keep its name. Oqoqo refuses the removal while a run of the agent is in progress, either a Test agent run or an experiment. Removing it again returns the same result.

Pass the revisions from `inspect_project_ai`. A refused removal changes nothing and returns one of these codes:

| Code | When |
| - | - |
| `configuration_changed` | A stale revision on `remove_custom_agent`. `details.currentRevision` has the current one. |
| `project_ai_configuration_changed` | A stale revision on the other actions |
| `project_ai_target_not_found` | The target is already removed. |

### test\_custom\_agent

**Test a custom agent (private beta).** Checks that a custom agent installs, starts, and answers, with one run of the Agent check task: **Agent default**, the **Raw Agent** treatment (no tools), no project files, and Evals and Insights off. It uses 1 run.

Changes data · You approve each call · CLI: [`oqoqo project ai test-agent`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-test-agent)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `agent_key` | string | Yes | The custom agent's `acp-` key from `inspect_project_ai` with `view: "agents"`. |
| `launch_attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 1 to 100 characters, and a retry returns the first launch instead of a second run. |

Poll the returned `launchId` with `get_launch_status`. Each finished run with these settings updates the agent's status in `inspect_project_ai`. A Test agent run is a check, not an experiment. It sends no notice and doesn't show on Home or in the dashboard's experiments list, but the CLI and the plugin still list it.

It refuses while `custom.testBlockers` names a blocker, with the first one's code:

| Code | Fix |
| - | - |
| `custom_agent_test_running` | A Test agent run with these settings is in progress. Open its `runUrl`. |
| `custom_agent_disabled` | Turn the agent on with `set_agents` in `manage_project_ai`. |
| `custom_agent_value_missing` | Set each named value in the dashboard with its `setupUrl`. |
| `custom_agent_default_model_disabled` | Send `set_model_enabled` with the blocker's `connectionId` and `modelId`. |

### get\_setup\_links

**Get secure setup links.** Returns the dashboard links for OAuth connections, API keys, secret headers, and other secret values.

Read-only · CLI: [`oqoqo setup links`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-setup-links)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |

**Result fields**

`issues` lists each machine, MCP server, CLI, and SDK in the project that still needs a required value or your account connection, with the `setupUrl` where a person adds it. An MCP server whose saved values aren't bound to its current address has a field of scope `address`, and its `setupUrl` is the server's **Tools** tab, where a person selects **Refresh**. The list is empty when nothing is missing.

### inspect\_mcp\_account

**Check your MCP server connection.** Checks whether your account can use an MCP server in a treatment, and returns the latest problem, a next step, and the dashboard setup link. A failed reconnect never replaces a working connection.

Read-only · CLI: [`oqoqo mcp accounts inspect`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-accounts-inspect)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `mcp_server_id` | string | Yes | The `mcp_` MCP server. |

**Result fields**

`ready`, `recovery` (with `message`, `action`, `setupUrl`, `retryAt`, and `apiKeyAlternative`), `setupUrl`, `redirectUri`, and `oauthAppConfigured`. Their meanings are under [`oqoqo mcp accounts inspect`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-accounts-inspect). When the server's saved values aren't bound to its current address, `ready` is `false` and `setupUrl` is the version's **Tools** tab, where a person selects **Refresh**.

### detect\_mcp\_auth\_mode

**Detect how an MCP server authenticates.** Probes the server's current definition and reports how it authenticates. It never returns the server's endpoint or credentials, and the OAuth app's Client ID and Client secret are entered only in the dashboard. See [MCP server sign-in](https://docs.oqoqo.ai/experiments/mcp-server-sign-in.md).

Read-only · CLI: [`oqoqo mcp accounts detect-auth`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-accounts-detect-auth)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `mcp_server_id` | string | Yes | The `mcp_` MCP server. |

**Result fields**

| Field | Meaning |
| - | - |
| `detectedAuthMode` | `oauth`, `headers`, `unreachable`, or `not_applicable` |
| `configurationMatches` | `false` when the detected mode differs from the saved one |
| `registration` | For `oauth`: `automatic`, `oauth_app_required`, or `unknown`. For `oauth_app_required` with no saved app, `setupUrl` opens the **OAuth app** section. |
| `redirectUri` | For `oauth`, the address to add to your OAuth app |
| `oauthAppConfigured` | Whether a Client ID is saved |
| `setupUrl` | The server's dashboard setup page |

### list\_mcp\_server\_tools

**List an MCP server's tools.** Reads the tools the server listed at Oqoqo's last check, with the check's `status`, `message`, time, tool count, and **Tools** page (`setupUrl`). Titles, descriptions, and hints are the server's own text.

Read-only · CLI: [`oqoqo mcp tools list`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `mcp_server_id` | string | Yes | The `mcp_` MCP server. |
| `version_id` | string | No | An `mcpver_` version. Default: the latest. |
| `query` | string | No | Only tools whose name, title, or description contains this text. |
| `after_position` | integer | No | The `nextAfterPosition` of the previous page. |
| `limit` | integer | No | Results per page, up to 200 (default 50). |
| `detail` | `summary`, `full` | No | `full` adds each tool's `inputSchema`. Default `summary`. |

Continue with `after_position` while `truncated` is true.

**Result fields**

The check's `status`, `message`, and time, the tool count, `setupUrl`, `truncated`, `nextAfterPosition`, `usageRunCount`, `lastChange`, `headerValuesBound`, and each tool with `canTurnOff`, `onRunCount`, `runCount`, `callCount`, `offInTreatmentCount`, and `offInTreatmentIds`. Their meanings are under [`oqoqo mcp tools list`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-list).

When `headerValuesBound` is `false`, only a person's **Refresh** at `setupUrl` binds the saved values: `refresh_mcp_server_tools` fails with `mcp_tool_check_needs_web` and launches stop with `mcp_header_values_unbound`. Give the person `setupUrl` instead of calling it ([Saved header values and the server address](https://docs.oqoqo.ai/experiments/tools.md#saved-header-values-and-the-server-address)).

### refresh\_mcp\_server\_tools

**Refresh an MCP server's tools.** Checks the server's tools now and returns the list as `list_mcp_server_tools` does. A running check is joined, not restarted. A server that needs your account connection or a header value returns that status and its `setupUrl`.

Changes data · CLI: [`oqoqo mcp tools refresh`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-refresh)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `mcp_server_id` | string | Yes | The `mcp_` MCP server. |
| `version_id` | string | No | An `mcpver_` version. Default: the latest. |
| `wait_ms` | integer | No | Wait up to 25,000 ms for the check to finish. |
| `query`, `after_position`, `limit`, `detail` | | No | As for `list_mcp_server_tools`. |

**Result fields**

The fields of `list_mcp_server_tools`, plus `refresh`, which is `running` until the check finishes. If the wait ends first, read the list again with `list_mcp_server_tools`.

It never sends saved header values to an address they aren't bound to, and it never binds them. When `headerValuesBound` is `false`, it fails with `mcp_tool_check_needs_web`. Give the person `details.setupUrl` (the version's **Tools** tab) to check the address and select **Refresh**, and don't call the tool again until they have.

### list\_github\_repositories

**List GitHub accounts and repositories for Ask Oqo (private beta).** Lists the GitHub accounts you can access, each with its default project, and every repository that has a project of its own, for [Ask Oqo in GitHub (CI/CD)](https://docs.oqoqo.ai/operate/ask-oqo-in-github.md). With `installation_id`, it lists one connected account's repositories from GitHub.

Read-only · CLI: [`oqoqo github repos list`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-repos-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `installation_id` | integer | No | A connected account's `installationId`. Lists that account's repositories, each with its project and `projectSource`. |
| `page` | integer | No | The page of the account's repositories, from `nextPage`. |

**Result fields**

| Field | Description |
| - | - |
| `accounts` | The GitHub accounts you can access that have the app: `installationId`, `accountLogin`, `accountType` (`organization`, `user`, or null), `accountUrl`, `avatarUrl`, `state` (`connected`, `available`, or `not_installed`), `defaultProject` (`projectId` and `projectName`, or null), and `settingsUrl`, GitHub's page for the app's repositories. |
| `repositories` | With no account selected, every repository that has a project of its own. For one account, one page of its repositories. Each has `repositoryId`, `fullName`, `repositoryUrl`, `installationId`, `private`, `project` (`projectId` and `projectName`, or null), and `projectSource`. |
| `projectSource` | `repository` when the project was chosen for the repository, `account` when it is the account's default project, and null when the repository has no project. |
| `private` | True or false in an account's page. It is null in the list of repositories with their own project. |
| `nextPage` | The next page of an account's repositories, or null. |
| `appName`, `appSlug`, `appUrl`, `installUrl` | The app's name, the name to mention after `@`, its page on GitHub, and GitHub's page to install it on an account. |

The person installs the app and chooses its repositories on GitHub, at `installUrl` and an account's `settingsUrl`. Only the person can open those pages. A comment must mention the app, `@` followed by `appSlug`, for Ask Oqo to answer. Without a GitHub connection, the tool returns `github_connection_required`, and `details.connectUrl` is the dashboard page where the person connects GitHub.

### manage\_github\_repository

**Connect a GitHub account or choose a repository's project (private beta).** Connects a GitHub account to the organization, sets an account's default project, or chooses one repository's project. The result has the same fields as `list_github_repositories`.

Changes data · You approve each call · CLI: [`oqoqo github accounts connect`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-connect), [`oqoqo github accounts default-project`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-default-project), [`oqoqo github repos link`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-repos-link), [`oqoqo github repos unlink`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-repos-unlink), [`oqoqo github accounts link-me`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-link-me)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `operation` | object | Yes | One change, chosen by `action`, as below. |

| `action` | Fields | What it does |
| - | - | - |
| `connect_account` | `installationId`, optional `projectId` | Connects an `available` account. With `projectId`, a newly connected account gets that default project. An account that is already connected keeps what it has. |
| `set_default_project` | `installationId`, `projectId` (a `prj_` ID or null) | Sets or changes a connected account's default project, or removes it with null. |
| `link` | `repositoryId`, `projectId` | Chooses or changes one repository's own project, which wins over the account's default. |
| `unlink` | `repositoryId` | Turns Ask Oqo off in one repository until `link` gives it a project. |
| `link_person` | | Records which GitHub account is the person's. Every action does this, so send it alone only when nothing else changes. |

Repeating an operation changes nothing. The tool can't install the app or change which repositories it can read. A refused call changes nothing and returns one of these codes:

| Code | When |
| - | - |
| `github_unavailable` | Ask Oqo in GitHub isn't enabled for your organization. |
| `github_connection_required` | You haven't connected GitHub. `details.connectUrl` is the dashboard page where you connect it. |
| `github_account_not_found` | The app isn't installed on the account, or you can't access the account on GitHub. |
| `github_account_not_connected` | The account isn't connected to your organization. |
| `github_account_in_use` | The account is connected to another Oqoqo organization. |
| `github_repository_not_found` | You can't access the repository on GitHub, or the app can't read it from a connected account. |
| `project_not_found` | The project doesn't exist or you can't open it. |

### disconnect\_github\_account

**Disconnect a GitHub account from Ask Oqo (private beta).** Disconnects a GitHub account from the organization. Ask Oqo stops answering in all of its repositories, and the account's default project and its repositories' projects are removed. The app stays installed on GitHub, and connecting the account again doesn't bring the projects back.

Destructive · CLI: [`oqoqo github accounts disconnect`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-disconnect)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `installation_id` | integer | Yes | The account's `installationId` from `list_github_repositories`. |

The result lists the accounts and repositories that remain.

## Related

> [card] [oqoqo project ai and setup](https://docs.oqoqo.ai/cli/agents-and-models.md)
>
> The matching CLI commands.

> [card] [Custom agents](https://docs.oqoqo.ai/setup/custom-agents.md)
>
> Add and test ACP custom agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.