Skip to main content
Manage agents, custom agents (private beta), model lists, Oqoqo AI defaults, MCP server authentication, dashboard setup links, and the GitHub accounts and repositories of Ask Oqo in GitHub (CI/CD) (private beta). Secrets stay in the dashboard (Secrets stay in the dashboard).
  • Badges are explained under Approvals.
  • project_id is optional on most tools; without it, the server picks a project for that call only (Projects).
  • expected_organization_id is an optional string on every write tool, omitted from parameter tables; pass organization.id from get_identity (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 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. 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. 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 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 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 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:

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 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: 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 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 Result fields ready, recovery (with message, action, setupUrl, retryAt, and apiKeyAlternative), setupUrl, redirectUri, and oauthAppConfigured. Their meanings are under 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. Read-only · CLI: oqoqo mcp accounts detect-auth Result fields

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 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. 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).

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 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). With installation_id, it lists one connected account’s repositories from GitHub. Read-only · CLI: oqoqo github repos list Result fields 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, oqoqo github accounts default-project, oqoqo github repos link, oqoqo github repos unlink, oqoqo github accounts link-me 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:

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 The result lists the accounts and repositories that remain.

oqoqo project ai and setup

The matching CLI commands.

Custom agents

Add and test ACP custom agents.