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

# AI Connectors

> Access Wildcard data from Claude, Claude Code, ChatGPT, or Codex

Connect Wildcard to **Claude, Claude Code, ChatGPT, or Codex** to
ask about your visitors, companies, and opportunities from the conversation.
Each app uses the same connector URL and your Wildcard account permissions.
You can also grant access to push visitors into HubSpot or adjust your hot-lead
settings.

Ask things like:

* *"Who visited our pricing page this week?"*
* *"Any hot leads from fintech companies in the last few days?"*
* *"Has anyone from Acme been on the site? Show me their journey."*
* *"Which accounts should I review next, and why? Include a brief for each."*
* *"Push that person into HubSpot."*

**Connector URL**

```
https://mcp.maverickintelligence.co/mcp
```

It is a remote [MCP](https://modelcontextprotocol.io) server over Streamable
HTTP. Other clients can connect if they support this transport and OAuth or
API-key headers.

***

## Connect your AI app

> [tab] Claude (web, desktop, mobile)
>
> **Free, Pro, and Max plans**
>
> The Free plan allows one custom connector.
>
> [Connect Wildcard to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Wildcard\&connectorUrl=https%3A%2F%2Fmcp.maverickintelligence.co%2Fmcp)
> opens the connector form with the name and URL filled in. Review it, add the
> connector, then choose **Connect**. You can do this in your browser without
> installing Claude Code. Alternatively, add it manually:
>
> 1. Go to **Customize › Connectors**
> 2. Click **Add custom connector**
> 3. Name it **Wildcard** and paste `https://mcp.maverickintelligence.co/mcp`
> 4. Click **Add**, then **Connect**
> 5. Enter the email you use for Wildcard, then enter the emailed sign-in code
>    in the authorization window that is already open
> 6. Choose your account if prompted, review the permissions, and click **Allow access**
>
> **Team and Enterprise plans**
>
> An owner adds the connector once for the whole organization under
> **Organization settings › Connectors › Add › Custom**. Each member then
> connects individually from **Customize › Connectors**, signing in with their own
> Wildcard email. Everyone sees only the data their own Wildcard account can see.
>
> If Claude asks for the connector type, choose **Web**. In the two-step dialog,
> select **Sign in now** for authentication and **Use Claude's published identity**
> for the OAuth client. Older screens call these **Always required** and
> **Use Anthropic's hosted client metadata**. The connector supports this option;
> no client ID or secret needs to be entered manually.
>
> See [Claude's custom connector instructions](https://claude.com/docs/connectors/custom/remote-mcp)
> for the current setup screens.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http wildcard https://mcp.maverickintelligence.co/mcp
> ```
>
> Run `/mcp` inside Claude Code to complete the sign-in. Claude Code opens a
> browser for the same email-code sign-in and consent screen.
>
> The command adds Wildcard for the current project. Add `--scope user` before
> `wildcard` if you want it available across your projects.
>
> See [Claude Code's MCP instructions](https://code.claude.com/docs/en/mcp).
>
> To use an API key instead of signing in:
>
> ```bash theme={null}
> claude mcp add --transport http wildcard \
>   https://mcp.maverickintelligence.co/mcp \
>   --header "X-API-Key: mk_live_your_key_here"
> ```

> [tab] ChatGPT
>
> For a custom connection, enable **Developer mode** in **Settings › Security
> and login**. Then:
>
> 1. Open **Plugins** in ChatGPT and select the **plus** button
> 2. Enter **Wildcard** as the name and a description such as
>    **Search my website visitors, companies, and opportunities**
> 3. Under **Connection**, enter `https://mcp.maverickintelligence.co/mcp`
> 4. Create the connection, then sign in through the Wildcard authorization screen
> 5. Enter your emailed sign-in code in that window, choose your account if
>    prompted, and approve the permissions
> 6. Start a new conversation and select the connection from the tools menu
>
> Developer mode depends on your account and workspace policy. Your administrator
> may need to enable it. Creating a custom connection does not publish a plugin
> to the directory.
>
> The connector provides standard `search` and `fetch` tools for research and
> company-knowledge workflows, as well as the detailed tools listed below.
> Availability of those ChatGPT features depends on your account.
>
> See the [official OpenAI connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt)
> for the current setup flow.

> [tab] Codex
>
> Add the connector from your terminal, then sign in:
>
> ```bash theme={null}
> codex mcp add wildcard --url https://mcp.maverickintelligence.co/mcp
> codex mcp login wildcard
> ```
>
> Enter the emailed Wildcard sign-in code in the browser window, choose your
> account if prompted, and approve the permissions. Use `/mcp` in Codex to check
> the connection.
>
> Local clients on the same Codex host share MCP configuration. You can also add
> the server URL under `[mcp_servers.wildcard]` in `~/.codex/config.toml`, then run
> `codex mcp login wildcard` to authenticate.
>
> For an API-key connection, set `WILDCARD_API_KEY` in the environment where you
> launch Codex, and add this configuration to `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.wildcard]
> url = "https://mcp.maverickintelligence.co/mcp"
>
> [mcp_servers.wildcard.env_http_headers]
> X-API-Key = "WILDCARD_API_KEY"
> ```
>
> API keys are read-only by default. See
> [OpenAI's MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
> for configuration options. ChatGPT web connections are configured separately.

> [tab] Other MCP clients
>
> Point any MCP client at `https://mcp.maverickintelligence.co/mcp` using the
> Streamable HTTP transport.
>
> The server implements OAuth 2.1 with Dynamic Client Registration
> ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) and Client ID Metadata
> Documents, so most clients discover and complete the flow with no manual
> configuration. Discovery starts from the `WWW-Authenticate` header on the 401:
>
> ```
> GET /.well-known/oauth-protected-resource
> GET /.well-known/oauth-authorization-server
> ```
>
> Clients that cannot do OAuth may instead send `X-API-Key: mk_live_...`.

***

## What your AI app can do

Every tool is scoped to the account you sign in with, and the connector can
only ever see what that account can see in the dashboard.

### Reading visitors

| Ask about | Tool |
| - | - |
| Search for records and retrieve sources for citations | `search`, `fetch` |
| Anyone on the site recently | `list_visitors` |
| Visitors to a specific page | `who_visited_page` |
| Qualified prospects | `list_hot_leads` |
| People from a named company | `find_visitors_at_company` |
| One person in detail | `get_visitor` |
| What someone actually looked at | `get_visitor_journey` |
| Companies rather than individuals | `list_companies`, `get_company` |
| A company's recorded visits, including linked people and referrers | `get_company_journey` |
| Accounts to review, with supporting evidence and next steps | `list_opportunities` |
| Totals and coverage | `get_account_stats` |
| Your hot-lead criteria | `get_hot_lead_criteria` |
| Which client sites you track | `list_tracked_clients` |

> [!NOTE]
>
> Most site traffic resolves to a **company** even when no individual is
> identified, so `list_companies` usually returns more than `list_visitors` for
> the same period. The connector explains this to the AI app so it can avoid
> reporting a person-level count as your total traffic.

Visitor and company journeys return recorded events in pages. Continue with
`nextCursor` while `hasMore` is true, including when a page contains no visible
events. `get_company_journey` accepts a `company_id`, an optional `limit`
(25 by default, up to 100), and an optional `cursor`. Company visits are
returned newest first and require an account-wide credential.

### Searching and citing records

`search` finds visible people and companies using short, space-separated
keywords. Every keyword must match the record. It checks people’s names,
emails, titles, companies, locations, and captured page paths, plus company
names, domains, industries, locations, and descriptions. Use the detailed
tools above for filters such as dates, qualification, or a visitor's journey.

Each search page examines up to 500 people and 500 companies and returns up to
10 matches from each. An empty page can still have more records to check;
follow `next_cursor` while `has_more` is true. With a client-scoped API key,
search covers only people within the permitted client sites.

`fetch` retrieves a result by its returned ID and checks access again. Search
results and fetched records include dashboard links the AI app can cite. You
must sign in to Wildcard to open those sources. Fetched text is capped at
50,000 characters and reports `metadata.truncated` if it reaches that limit.

### Reviewing opportunities

`list_opportunities` uses the same recorded-activity rules as the app's
Opportunity inbox. Each result includes its priority, supporting evidence,
known CRM state, and a suggested next step. It requires an account-wide
credential with `read:visitors` permission.

For example, ask: *"Show five accounts with open deals that are worth reviewing,
and include a brief for each."* The corresponding tool arguments are:

```json theme={null}
{
  "category": "pipeline",
  "limit": 5,
  "include_briefs": true
}
```

| Argument | Accepted values | Default |
| - | - | - |
| `category` | `all`, `prospect`, `pipeline`, `customer` | `all` |
| `limit` | An integer from 1 to 25 | `10` |
| `include_briefs` | `true` or `false` | `false` |
| `include_reviewed` | `true` to also include reviewed, snoozed and archived matches | `false` |

The app's review decisions are shared with this tool. By default, accounts
already reviewed, still snoozed, or archived are omitted. A reviewed account
can return after new activity; a snoozed account returns when its snooze expires.
Use `include_reviewed: true` to inspect matching accounts regardless of review
status. Results include their saved status and review metadata, including notes.
This option does not expand the activity sample or include historical-only
records. Review actions and notes are managed in the app's Opportunities view.

The shortlist considers up to 100 most recently seen companies in the standard
dashboard view. Partner-managed records are excluded. Accounts qualify when
last seen within 14 days and they match your configured lead criteria, have
at least three lifetime visits, or have an open deal on record. Explicit
opt-outs are excluded. “Review now” means last seen within seven days with
either an open deal or both a criteria match and three lifetime visits.

The response reports how many companies were sampled, whether source data is
partial, and whether more matching results exist than were returned. It has
no pagination cursor. Use `category` and `limit` to focus the shortlist, or
the app's Companies view to explore further.

These are recorded signals for review. Visit counts are lifetime totals;
activity alone does not establish purchase intent. CRM information may be
stale or incomplete. The tool returns evidence and optional briefs without
sending outreach or changing CRM records.

### Making changes

These four tools change live data and require the corresponding write
permission. The connector identifies them as write tools; your AI app's approval
settings determine when it asks for confirmation. Approve only changes you intend.

| Tool | What it does |
| - | - |
| `push_visitor_to_hubspot` | Creates or updates the visitor as a contact in your connected HubSpot, with their company, and associates the two. Matches on email and domain, so it updates existing records rather than duplicating them. Requires an account-wide credential. |
| `push_visitor_to_attio` | Creates or finds the visitor in your connected Attio, optionally with their company, and associates them. Existing fields are preserved. Requires an account-wide credential. |
| `update_hot_lead_criteria` | Changes the ideal customer profile that decides who counts as a hot lead. Merges with your existing settings — only the criteria you name are changed. Account-wide. |
| `exclude_company_domains` | Suppresses visitors from given company domains, for hiding your own staff and known bots. In `replace` mode it removes domains not listed, so review the current list first. |

***

## Authentication

There are two ways to connect. **Signing in is the recommended one.**

### Signing in (OAuth)

Your AI app opens Wildcard's authorization screen. Enter your email, then type
the emailed sign-in code in that same window. Pick your account if your address
has more than one, and approve the requested permissions. Access is tied to
your own Wildcard account. Read access is granted by default. On the approval
screen, you can separately opt in to pushing visitors to HubSpot or Attio and changing
hot-lead settings. Every write option starts unchecked, even if your AI app
requests them. Reconnect your AI app to change the permissions on an existing
connection. The token response tells your AI app which scopes you granted.

Permissions are requested individually:

| Permission | Grants |
| - | - |
| `read:visitors` | See the people and companies visiting your website |
| `write:crm` | Push visitors into your connected HubSpot |
| `write:attio` | Push visitors into your connected Attio |
| `write:settings` | Change hot-lead criteria and excluded domains |
| `offline_access` | Stay connected without signing in again |

Access tokens last one hour. If you grant `offline_access`, the client can
refresh them automatically. Refresh tokens rotate and expire after 30 days
without renewal.

### API key

For automation, or clients that cannot do OAuth, send your existing Developer
API key as an `X-API-Key` header. See [Authentication](https://docs.trywildcard.ai/authentication.md) for how
to create one.

> [!WARNING]
>
> **API keys are read-only for the connector by default.** Your `mk_live_` keys
> were issued for a read-only REST API, so the connector will not let one write
> to your HubSpot or change your settings — a key you created for reporting
> cannot be turned into a key that edits your CRM just because it was pasted
> somewhere new.
>
> Write access for a specific key is enabled per key by Wildcard support — email
> [support@trywildcard.ai](mailto:support@trywildcard.ai) if you need it for an automation. For anything interactive, sign in with
> OAuth instead.

### Agencies and partners

If you hold a **domain-scoped** API key — one restricted to particular client
sites — the connector honours that restriction on every tool. Visitors outside
your scope are not returned, and are reported as "not found" rather than as
"not allowed", so the connector cannot be used to discover which other clients
exist.

Use `list_tracked_clients` to see the sites available to your credential, then
pass `domain` or `client_ref` to supported visitor tools to narrow further.
OAuth connections are account-wide, so use a scoped API key when you need a
per-client boundary.

Account-wide tools — `list_companies`, `get_company`, `get_company_journey`,
`list_opportunities`, `get_account_stats`, and `get_hot_lead_criteria` — are unavailable to
client-scoped keys. Their company activity, totals, or settings combine data
across client sites. Adding a domain filter cannot grant access to them.
Account-wide settings writes also require an account-wide credential.
`push_visitor_to_hubspot` also requires account-wide access because CRM field
mappings read person and company records that combine data across client sites.

Client-scoped visitor results omit activity totals, first/last-seen dates,
hot-lead qualification, and traffic/ad-platform attribution that combine data
across sites. Their page summaries and page matching use only the captured and
last-page URLs individually verified within the allowed sites, so they can be
incomplete. Filters that require combined recency or hot-lead data are
unavailable to these keys. Use `get_visitor_journey` for recorded events within
your permitted sites.

***

## Limits

| | |
| - | - |
| Rate limit | 1,000 requests per hour. OAuth connections share an allowance per Wildcard account. API-key connections share their REST API allowance; domain-scoped keys have a separate allowance per key. |
| Rows per call | Visitor/company lists and company journeys: 100 maximum, 25 by default, with pagination. Search: up to 10 people and 10 companies per page. Opportunities: 25 maximum, 10 by default, from a sample of up to 100 recent companies. |
| Result size | Large results are truncated with a note telling the AI app to narrow the query. |
| Request timeout | Requests can time out after about 29 seconds. Use narrower queries and continue through available pagination cursors. |

***

## Privacy and safety

* **Your AI app sees only what your account sees.** Excluded domains, excluded
  paths and suppressed visitors stay hidden.
* **Write permissions are separate.** Grant only `read:visitors` if you want
  data access without CRM or settings changes. Review your AI app's tool approvals
  before enabling write permissions.
* **You can block individual tools.** In Claude, open the connector under
  **Customize › Connectors** and set a tool's permission to **Blocked**. Codex
  supports tool allowlists and denylists in its MCP configuration.
* **Disconnect at any time** by removing the connector or signing out in your
  AI app. Revoke API keys from your dashboard. Removing a client connection
  stops that client using its saved credentials; it is not a server-side
  revocation of every previously issued token.
* **Tool arguments are not logged.** Request logs record which tools ran, not
  the page paths or company names you asked about.

***

## Troubleshooting

> [accordion] 'Couldn't reach the MCP server'
>
> Check the URL includes the `/mcp` path — `https://mcp.maverickintelligence.co/mcp`,
> not the bare domain. The path is part of the server's identity, and a token
> issued for the bare domain will not be accepted.

> [accordion] The sign-in code says it's no longer valid
>
> Codes are single-use and expire after 15 minutes. They are tied to the
> connection attempt that created them. Start again from your AI app and enter
> the newest code in the authorization window it opens.

> [accordion] 'No active Wildcard account is associated with...'
>
> Use the email address you sign in to the dashboard with. Any of your account's
> registered addresses works, including secondary contacts. If you have just been
> added to an account, ask the account owner to confirm your address was saved.

> [accordion] My AI app says it doesn't have permission to write
>
> Either you connected with an API key (read-only by default — see the warning
> above), or the connection has only read permission. Reconnect with OAuth and
> select the HubSpot or settings write permission on Wildcard's approval screen.
> If your AI app does not show the approval screen again, disconnect it first and
> connect again. Existing tokens keep their original permissions until replaced.

> [accordion] My AI app returns fewer visitors than the dashboard shows
>
> Visitor and company list tools default to 25 rows; ask the app to continue
> through any available pages. Search has its own page limits described above.
> Many visits resolve to a company without identifying a person;
> ask about companies to see the fuller picture.

> [accordion] ChatGPT does not show Developer mode or the connector
>
> Developer mode can be restricted by your account or workspace policy. Ask your
> workspace administrator about access. A connection added to Codex's local
> configuration does not appear automatically in ChatGPT web; add it from
> ChatGPT's Plugins page. After a connector update, refresh its metadata and
> start a new conversation.

> [accordion] Rate limited
>
> The limit is 1,000 requests per hour. OAuth connections share an allowance per
> Wildcard account. API-key connections share their REST API allowance;
> domain-scoped keys have a separate allowance per key. A long analysis session
> can consume the allowance. The limit resets on the hour.


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