Use Onsomble with OpenAI

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:

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

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.

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.

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.

OpenAI’s guides: Developer mode setup and account and workspace access. 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:

codex mcp add onsomble --url https://mcp.onsomble.ai/mcp

Run codex mcp login onsomble.

Approve

OpenAI’s own guide: Using MCP with the Codex CLI.

Use it

Name Onsomble in your first message and name the Site you mean. A few to start with are on the overview. To make the assistant read the results like an analyst, install the Onsomble skills 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. 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.

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

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

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)

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.

In the GPT editor, open Configure → Actions and select Create new action.
Import the schema from https://docs.onsomble.ai/openapi/gpt-actions-v1.json, or paste its contents.
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.

Getting started

Sites

Prompts

Scans

Understanding results

For agencies

Connect AI assistants

Assistant

Account & billing

Concepts & reference

Onsomble API

Changelog

Use Onsomble with OpenAI

ChatGPT

Codex

Use it

API keys for scripts and CI

The Responses API

The Agents SDK

Custom GPTs

​ChatGPT

​Codex

​Use it

​API keys for scripts and CI

​The Responses API

​The Agents SDK

​Custom GPTs

ChatGPT

Codex

Use it

API keys for scripts and CI

The Responses API

The Agents SDK

Custom GPTs