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

# Use Onsomble with OpenAI

> Connect Onsomble to ChatGPT and Codex by signing in, or with an API key for the Responses API, the Agents SDK, and custom GPTs.

Connect Onsomble to ChatGPT or Codex and you can run your AI discoverability work by talking to it: set up a Site, add the prompts you track, run a Scan, or ask how you are showing up in AI answers.

The connection is one address:

```text theme={null}
https://mcp.onsomble.ai/mcp
```

You sign in to Onsomble the first time you connect, so no keys change hands. For the Responses API, the Agents SDK, and custom GPTs, use an [API key](#api-keys-for-scripts-and-ci) instead.

## ChatGPT

Set up the connection on **chatgpt.com** using an account with access to custom apps. In a managed workspace, ask an administrator to make Onsomble available and enable the actions you need. Reading results and changing your Onsomble setup require different tool permissions.

<Steps>
  <Step title="Turn on developer mode">
    Open **Settings → Security and login** and turn on **Developer mode**.
    Some workspace accounts use **Settings → Apps → Advanced Settings**.
    If the option is unavailable, follow OpenAI’s account-specific guide below
    or ask your workspace administrator.
  </Step>

  <Step title="Add the connector">
    Open **Plugins**, use the **+** button, paste the address above, and name it
    **Onsomble**.
    If your workspace uses Apps settings, choose **Apps → Create** instead.
    If an administrator has already added Onsomble, select that existing app.
  </Step>

  <Step title="Sign in and approve">
    Sign in to Onsomble in the browser that opens and approve access. Enable the
    connector in a conversation and ask it to list your Sites. Check that the
    actions needed for your task are enabled before asking it to change data.
  </Step>
</Steps>

OpenAI's guides: [Developer mode setup](https://developers.openai.com/api/docs/guides/developer-mode) and [account and workspace access](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

If the connector stops appearing in the picker (a known ChatGPT quirk with custom connectors), remove it and add it again.

## Codex

Add the server with one command:

```bash theme={null}
codex mcp add onsomble --url https://mcp.onsomble.ai/mcp
```

<Steps>
  <Step title="Log in">Run `codex mcp login onsomble`.</Step>

  <Step title="Approve">
    Sign in to Onsomble in the browser that opens and approve access.
  </Step>
</Steps>

OpenAI's own guide: [Using MCP with the Codex CLI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Use it

Name Onsomble in your first message and name the Site you mean. A few to start with are on the [overview](/developers/connect/overview). To make the assistant read the results like an analyst, install the [Onsomble skills](/developers/connect/skill) alongside the connection.

## API keys for scripts and CI

For a product, an internal agent, or a shareable custom GPT, authenticate with an Onsomble API key instead of signing in. Create one in **Settings → Account → API Keys**: see the [API overview](/developers/quickstart). Keys start with `ons_` and are shown once at creation.

The server publishes tools for reading results and managing your Onsomble setup. Examples include:

| Tool | What it answers |
| - | - |
| `list_sites` | Which Sites (and, for agencies, Clients) can this key see? |
| `get_visibility_overview` | Where does the brand stand right now, and what changed? |
| `get_visibility_timeline` | How has a metric trended across Scans? |
| `get_prompt_results` | What did each AI platform actually answer? |
| `get_references` | Which domains and pages do AI answers cite? |
| `get_competitor_insights` | How do tracked and newly discovered competitors compare? |
| `get_narratives` | What stories do AI answers tell about the brand? |
| `get_recommendations` | What actions would improve discoverability? |
| `get_region_visibility` | How does visibility differ by region? |
| `trigger_scan` | Start a new Scan for a Site. |
| `get_scan_status` | Is a Scan finished yet? |
| `get_scan_config` | What questions, markets, platforms and schedule are configured? |
| `manage_client` | Create or update a Client in an agency account. |
| `create_site` | Create a Site under the selected account or Client. |
| `manage_site` | Update a Site and its business profile. |
| `manage_prompts` | Add or update the questions a Site tracks. |
| `manage_schedule` | Change the Scan frequency or pause recurring scans. |

Onsomble MCP can read results and, with the required permissions, change Clients, Sites, scan configuration and schedules. Starting a Scan uses scan allowance. Review and approve changes and scan runs before your assistant carries them out. The tools available to a connection depend on its permissions.

### The Responses API

Attach the server as a hosted MCP tool. OpenAI's platform makes the tool calls; you never proxy the traffic.

```python theme={null}
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    tools=[
        {
            "type": "mcp",
            "server_label": "onsomble",
            "server_url": "https://mcp.onsomble.ai/mcp",
            "authorization": "ons_your_api_key",
            "require_approval": {
                "never": {"tool_names": ["list_sites", "get_visibility_overview"]}
            },
        }
    ],
    input="How visible is acme.example in AI assistants this month?",
)

print(response.output_text)
```

This example skips approval only for the two named read tools. Other calls still require approval, including tools that change account data, scan configuration or schedules. Starting a Scan is one of several write actions.

### The Agents SDK

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Agent, hostedMcpTool, run } from "@openai/agents";

  const agent = new Agent({
    name: "Discoverability analyst",
    tools: [
      hostedMcpTool({
        serverLabel: "onsomble",
        serverUrl: "https://mcp.onsomble.ai/mcp",
        authorization: "ons_your_api_key",
        requireApproval: "always",
      }),
    ],
  });

  const result = await run(
    agent,
    "Summarise this month's visibility for acme.example.",
  );
  console.log(result.finalOutput);
  ```

  ```python Python theme={null}
  from agents import Agent, HostedMCPTool, Runner

  agent = Agent(
      name="Discoverability analyst",
      tools=[
          HostedMCPTool(
              tool_config={
                  "type": "mcp",
                  "server_label": "onsomble",
                  "server_url": "https://mcp.onsomble.ai/mcp",
                  "authorization": "ons_your_api_key",
                  "require_approval": "always",
              }
          )
      ],
  )

  result = Runner.run_sync(
      agent, "Summarise this month's visibility for acme.example."
  )
  print(result.final_output)
  ```
</CodeGroup>

These SDK examples return tool approval requests. Your application must show each request to the user and pass their decision back through the SDK’s approval flow before continuing the run.

The SDK also supports connecting directly with its Streamable HTTP client (`MCPServerStreamableHttp`) when you want the tool calls to run from your own process instead of OpenAI's platform.

### Custom GPTs

Custom GPTs use GPT Actions, which call the REST API from an OpenAPI schema. Onsomble publishes a schema curated for Actions: Sites, Scan control, and the headline reports, with pagination trimmed for single-call use.

1. In the GPT editor, open **Configure → Actions** and select **Create new action**.
2. Import the schema from `https://docs.onsomble.ai/openapi/gpt-actions-v1.json`, or paste its contents.
3. Set **Authentication** to **API Key** with auth type **Bearer**, and paste your API key.

The schema marks starting a Scan as consequential, so ChatGPT asks the user for confirmation before calling it. Read operations run without confirmation.


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