# SoftwareIQ MCP agent instructions

Server: https://mcp.softwareiq.io/mcp
Human guide: https://www.softwareiq.io/documentation/mcp

## Research data in your agent

SoftwareIQ MCP is a licensed connection between an AI agent and entitled SoftwareIQ research datasets. The agent discovers available tools, requests structured observations, and uses their metadata to interpret the result.

Operating KPIs, management guidance, Job Postings, taxonomy, availability, and Adoption Signals share the identifiers and definitions used by the REST API. MCP returns data to the agent; it does not change company data or execute trades.

## Access and authentication

MCP is licensed per user and provisioned for each approved named user under an agreed contract. Your Research login is the same identity, but a Research subscription or website license does not automatically grant MCP access.

Auth0 signs you in. SoftwareIQ checks the organization contract, user/profile grants, token scopes, and usage limits for each request. Only entitled tools appear in tools/list. REST API keys are separate credentials and are not interchangeable with MCP OAuth tokens.

Contact us for MCP through the contact form on the Research MCP page if you have not been provisioned. We agree on datasets, users, and license terms before enabling access. Once approved, add the server URL in your agent client and complete its OAuth flow. Signing in to the research website alone does not authenticate your agent.

## Start a reproducible research query

Resolve company_id with search_companies, inspect the relevant dataset, and request a bounded date range. Retain the response metadata and any source-check links when sharing results.

Follow meta.next_cursor until meta.has_more is false, keeping the same filters. Adoption cursors are also tied to a committed publication; restart the extract if it changes. Page size defaults to 100 and is capped at 500 (company search advertises a maximum of 100).

Adoption queries accept one company_id or ticker. Sources are npm, PyPI, NuGet, Docker, and Terraform. get_adoption_series requires period_start and period_end; grain defaults to weekly and series_kind to aggregate. Date bounds select period_end. Weekly rows describe Monday–Sunday intervals.

Aggregate adoption rows retain value and adjusted_value. Version rows use series_kind=versions and preserve sparse membership, including residual/unattributed versions. An absent version point is unknown. Adoption data uses its own publication schema; frontend release versions are a separate presentation format.

## Interpret observations carefully

Never coerce null or an absent observation to zero. A known zero is distinct from missing coverage. Preserve hiring classification versions and review collection continuity before calculating changes.

Package downloads, container pulls, and provider activity have different units. They are not paid seats, unique users, revenue, or management-reported consumption. Review artifact mapping and customer-visible adoption events before interpreting inflections.

KPI series are current corrected facts, not a historical as-known-at-the-time archive. Preserve dated extracts if you need point-in-time research. Cite returned source-check URLs and include dataset freshness and relevant version metadata.

## Connection help

Discovery or connection failure: confirm the full /mcp URL, your client’s remote HTTP support, and any workspace connector restrictions. SoftwareIQ support can supply client registration details.

401: reconnect or sign in again with the approved account. OAuth tokens may expire; your client handles refresh when configured. Never paste tokens into chat or documentation.

403 or an empty tool list: check that your user/profile and organization contract include the requested resources and your OAuth token has the corresponding read scopes. Research website access alone is not an MCP grant.

429: respect Retry-After and reduce concurrent requests. Hiring and adoption series cost two units; other tool calls cost one. The default budget is 60 units per minute per organization, subject to the contract.

Changed adoption publication or expired cursor: restart with the original filters. If support is needed, include the returned request_id, client name, and failure step without credentials.

## Tools

- `search_companies`: Resolve stable company_id values from ticker or current coverage metadata.
- `describe_dataset`: Inspect dataset freshness and classification metadata.
- `get_kpi_series`: Read current corrected annual or quarterly KPI observations.
- `get_kpi_source`: Retrieve a source-check link for a KPI fact.
- `get_guidance_series`: Read published management guidance observations.
- `get_job_posting_series`: Read bounded daily or weekly hiring observations and supported classified intersections.
- `get_job_taxonomy`: Resolve versioned taxonomy member labels and hierarchy.
- `list_job_classifiers`: Find compatible classifier, taxonomy, and company-rule-set versions.
- `get_data_availability`: Review hiring collection gaps, migrations, and comparability events.
- `search_adoption_projects`: Discover software projects for one company_id or ticker.
- `get_adoption_artifacts`: Resolve package, container, and provider artifact identities.
- `get_adoption_versions`: Resolve software version identities and first/last observed dates.
- `get_adoption_events`: Review customer-visible adoption events and adjustment context.
- `get_adoption_series`: Read date-bounded daily/weekly aggregate or sparse version activity.

## Client setup

### Codex

Add SoftwareIQ to Codex, sign in, and start a new session.

1. Confirm your connection details: Have the connection details we sent you ready.

2. Add SoftwareIQ: Run the command below in your terminal. Replace YOUR_MCP_CLIENT_ID with the value in your SoftwareIQ setup details.

```sh
codex mcp add softwareiq --url https://mcp.softwareiq.io/mcp --oauth-client-id YOUR_MCP_CLIENT_ID
```

3. Sign in to SoftwareIQ: Run the command below and sign in with your SoftwareIQ account in the browser. Return to Codex when sign-in is complete.

```sh
codex mcp login softwareiq
```

4. Check the configuration: Check that SoftwareIQ appears in the list.

```sh
codex mcp list
```

5. Start using SoftwareIQ: Start a new Codex session or reload your editor, then ask the question below.

Configure through config.toml

Instead of the add command, add this server entry to ~/.codex/config.toml. Replace the placeholder client ID, then run codex mcp login softwareiq. Keep only one softwareiq entry.

```toml
[mcp_servers.softwareiq]
url = "https://mcp.softwareiq.io/mcp"

[mcp_servers.softwareiq.oauth]
client_id = "YOUR_MCP_CLIENT_ID"
```

Official instructions: https://learn.chatgpt.com/docs/extend/mcp?surface=cli

### Claude

Add SoftwareIQ in Claude’s connectors, then sign in to your SoftwareIQ account.

1. Open your connectors: Open Customize → Connectors and choose Add custom connector. For an organization, ask its owner to add SoftwareIQ under Organization settings → Connectors.

2. Add the server: Name the connection SoftwareIQ and paste the connection URL below.

```text
https://mcp.softwareiq.io/mcp
```

3. Enter your setup details: Choose the sign-in option. If Claude asks for a Client ID or other setup fields, enter the details we sent you.

4. Connect your account: Finish adding the connector, choose Connect, and sign in with your SoftwareIQ account.

5. Enable it in a conversation: Open the conversation’s + menu, choose Connectors, and enable SoftwareIQ. Ask the connection-check question below.

Official instructions: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp

### ChatGPT

Add SoftwareIQ to ChatGPT, sign in, and select it in a conversation.

1. Confirm workspace access: Open ChatGPT Plugins, choose the plus button, and select Add custom MCP server. Ask your administrator to allow custom connections if this option is unavailable.

2. Create the connection: Name it SoftwareIQ, add a short description, choose the public endpoint option, and paste the connection URL. Select OAuth if asked to choose an authentication method.

```text
https://mcp.softwareiq.io/mcp
```

3. Enter your setup details: If ChatGPT asks for a Client ID or other setup fields, enter the details we sent you.

4. Sign in to SoftwareIQ: Finish creating the connection and sign in with your SoftwareIQ account when prompted.

5. Use it in a conversation: Install the resulting custom plugin, start a new conversation, type @, and select SoftwareIQ. Ask the connection-check question below.

Official instructions: https://developers.openai.com/plugins/deploy/connect-chatgpt