Connect Semantil to your AI agent

Semantil runs as a hosted MCP server at https://mcp.semantil.com/mcp. There is nothing to install. Connect with sign-in (OAuth) when your client supports it, or with an API key when it does not.

MCP access

MCP needs an account whose plan or invitation includes MCP. Accounts are by invitation; request access if you do not have one yet.

Option 1: sign in (recommended)

1. Add the server URL

   In your client, add a remote MCP server with this URL:

   https://mcp.semantil.com/mcp

   • ChatGPT: in a workspace with Developer mode, add an MCP connection.
   • Claude: Connectors → Add custom connector.
   • Claude Code: claude mcp add --transport http semantil https://mcp.semantil.com/mcp, then run /mcp and choose Authenticate.

2. Sign in to Semantil

   Choose Connect or Sign in and log in with your Semantil account. No secret is copied anywhere.

3. Check it works

   Ask the agent to check your Semantil account (see Verify).

Option 2: API key

Use a key for clients without OAuth and for headless agents.

1. Create a key

   Create one in API keys. New keys include MCP access when your plan includes it. The secret is shown once, together with a ready-to-paste Claude Code command.

2. Keep the key in an environment variable

   export SEMANTIL_MCP_KEY="YOUR_API_KEY"

   Do not commit the key, put it in a URL, or paste it into a prompt. Use a separate key for each client so you can rotate one connection independently.

3. Add the remote server

   Claude Code

   The single quotes keep the environment-variable reference instead of copying the secret into the saved configuration.

   claude mcp add-json --scope user semantil \
     '{"type":"http","url":"https://mcp.semantil.com/mcp","headers":{"Authorization":"Bearer ${SEMANTIL_MCP_KEY}"}}'

   Verify the connection:

   claude mcp get semantil

   Cursor

   Add this server to your global ~/.cursor/mcp.json or the project’s .cursor/mcp.json:

   {
     "mcpServers": {
       "semantil": {
         "url": "https://mcp.semantil.com/mcp",
         "headers": {
           "Authorization": "Bearer ${env:SEMANTIL_MCP_KEY}"
         }
       }
     }
   }

   Restart Cursor or reload its MCP servers after setting the environment variable.

   Codex

   Set SEMANTIL_MCP_KEY, then add the hosted server to ~/.codex/config.toml:

   [mcp_servers.semantil]
   url = "https://mcp.semantil.com/mcp"
   bearer_token_env_var = "SEMANTIL_MCP_KEY"

   Restart Codex after changing the environment or configuration.

   Other clients

   Use a client that supports remote Streamable HTTP servers and custom request headers:

   URL: https://mcp.semantil.com/mcp
   Authorization: Bearer YOUR_API_KEY

Verify with one prompt

Ask your agent:

Use Semantil to check my account and remaining credits. Then list the
Semantil tools available to you without running a paid data request.

The connection is ready when the agent can call semantil_account and list the tools granted to your account or key.

Available tools

The server exposes only the tools your plan and credential allow. Agents receive the current input schema during MCP tool discovery, so you do not need to copy parameter definitions into a prompt.

Tool	Use it for
semantil_discover_market	Define or qualify a market and return companies in it with the reason each matched.
semantil_search	Find companies with keyword or semantic search and structured filters.
semantil_lookalike	Find companies similar to one seed domain.
semantil_enrich	Return the stored record for up to 25 known domains.
semantil_breakdown	Measure the exact distribution of one field over a filtered population.
semantil_compare_cohorts	Compare two groups on named dimensions.
semantil_explain_cohort	Profile automatically what stands out in one group.
semantil_discover_segments	Find combinations of signals that concentrate inside a group.
semantil_rank_segments	Rank segments where a target group is large and a product or competitor is rare.
semantil_lists	Find your saved lists and public lists, usable as filters or exclusions.
semantil_list_create	Save a new working list.
semantil_list_add	Add the next batch of domains to the same list, without duplicates.
semantil_account	Check the current plan and credit usage.

Market counts describe Semantil’s indexed domains rather than the real-world total addressable market. Cohort differences are associations, not causal claims.

Several values in one filter

On some multi-valued fields (for example payment methods or shipping carriers), several values in one filter mean the company must have all of them. When you mean any of them, ask for one value per request.

Credits and access

• MCP uses the same workspace credits and request limits as the REST API.
• semantil_account, breakdowns, comparisons, segments and list tools cost 0 credits.
• Tools that return companies use 1 credit per returned company; the contact add-on in semantil_enrich costs more, and only when contacts are found.
• Creating more keys does not multiply the workspace budget.
• Revoking a key or an OAuth connection takes effect on the next request.

A key is sent only in the HTTPS Authorization header and is never part of the endpoint URL. Semantil checks the credential before returning the tool list or running a tool.

Troubleshooting

401 A Semantil access token is required.

The client sent no Authorization header. With OAuth, sign in again from the client. With a key, confirm that SEMANTIL_MCP_KEY is visible to the process that runs your MCP client (desktop apps often do not see shell variables), then reload the connection.

This credential cannot access Semantil MCP.

The key was created without MCP access, or the account does not include MCP. Sign in with OAuth instead, or create a new key in API keys: new keys include MCP access when your plan includes it.

This credential does not grant any MCP tools.

The credential is valid but none of its permissions map to an MCP tool. Create a new key with the default access.

MCP access is rate limited.

Wait for the time in the Retry-After header. Check usage and credits or call semantil_account; MCP cannot bypass the workspace plan, credit balance or per-key limits.