# MCP

The EnvoAPI MCP endpoint is `https://api.envoapi.com/mcp`. Add it as a remote connector in an MCP client that supports Streamable HTTP. Clients that support MCP OAuth can sign in to EnvoAPI and authorize account access. Clients with custom authorization headers can use an existing EnvoAPI Customer API Key:

* URL: `https://api.envoapi.com/mcp`
* Transport: Streamable HTTP
* Header: `Authorization: Bearer <ENVO_API_KEY>`

Keep API keys in your client's secret configuration. OAuth connections are bound to your account and share its Credits and limits; they do not require a Customer API Key. Browser origins and the RapidAPI hostname are not supported. Operators can disable MCP with `GATEWAY_MCP_ENABLED=false`.

The server exposes 35 tools covering the 52 public operation variants. `tools/list` includes readable titles, descriptions, arguments, defaults, billing guidance and success output schemas. Initialization supplies guidance for combining tools. Initialization and discovery authenticate the connection without consuming lookup Credits or account RPM. Restricted accounts can discover tools, but lookups still enforce account access, Credits and limits.

## Ask naturally in ChatGPT or Claude

After connecting, make EnvoAPI available to the conversation and enable the relevant tools under your client's permissions. Try “Find the founders of Stripe” or “Find software engineering jobs at Microsoft in London.” The descriptions help the assistant choose tools without requiring “use EnvoAPI” in every message. Tool selection still depends on the client, model, enabled tools and conversation; the server cannot force selection or guarantee a particular chain.

If your client offers a connector description, you can use:

> Research companies and professional profiles using EnvoAPI. Find company founders, leadership and employees; resolve company names or domains; retrieve professional background, jobs, posts and requested contact information. Company research can continue into filtered people searches. Does not establish legal ownership or shareholdings. Lookups may consume EnvoAPI Credits.

For a stronger personal preference, save this in your client's persistent instructions if supported:

> When I ask for company or professional-profile research that EnvoAPI can answer, use the connected EnvoAPI tools when available, without requiring me to name the connector. Follow its tool guidance, respect my spending limits, cite returned sources, and state when evidence is incomplete. Clarify legal ownership versus founding when necessary.

After a server metadata update, refresh the connector's tools if your client supports it, or reconnect, and test in a fresh conversation. Check that the expected tools are enabled. For current setup controls, see the official [ChatGPT connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt) and [Claude connector guide](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities).

## Example: find a company's founders

For “Find the founders of Stripe,” the assistant can combine the existing tools:

1. Reuse a company ID, slug or LinkedIn URL already established in the conversation. Otherwise search the company name with `search_companies_by_keyword`. When a domain such as `stripe.com` is supplied or established, start with `search_companies_by_domain`; use name search if the successful response has no suitable match. Do not guess a domain from the name.
2. Match the intended company, clarifying ambiguous results. Search returns `data.companies[].slug` and `linkedinUrl`, **not** an Envo company ID. Call `get_company_details` with the selected slug or URL and read **`data.publicId`**.
3. Call `search_people_by_keyword` with `keywords: "founder"` and `currentCompany` set to that returned ID. To cover historical founders, search `pastCompany` separately when needed. Applying both filters at once narrows the result rather than combining current and former employees.
4. Check that each person's role belongs to the target company. Use `get_profile_details` or `get_profile_full_experience` only if the returned positions do not provide enough evidence. Cite the company and profile URLs, and explain any uncertainty.

This is client planning guidance. Each step is a separate potentially billable call; EnvoAPI does not run the chain automatically. Stop when the question is answered or the user's limit is reached. Empty results do not prove there are no founders. A founder headline at another company is insufficient evidence, and a CEO is not necessarily a founder. For “Who owns Stripe?”, clarify whether the user means founders or legal ownership: these tools do not establish shareholders, equity stakes or beneficial ownership.

Do not switch tools or retry automatically after authentication, account, Credit, rate-limit or service errors. An error is different from a successful empty search. Contact lookups are unnecessary for identifying founders unless contact information was requested.

## Make a call

For a legacy MCP client, initialize using its supported protocol version, then send a tool request. Every request needs the authorization header. Responses are JSON; no session ID is required.

```bash
curl https://api.envoapi.com/mcp \
  --header "Authorization: Bearer $ENVO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

curl https://api.envoapi.com/mcp \
  --header "Authorization: Bearer $ENVO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2025-03-26' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_profile_details","arguments":{"username":"example-profile"}}}'
```

The current MCP protocol is also supported through SDK version negotiation. Use your client's protocol implementation to supply its request headers and metadata.

## Arguments and pagination

Tool argument names match public API query parameters. When a tool supports multiple identifiers, provide **exactly one** of `url`, `username`, `slug`, or `publicId` as listed below. An identifier accepted by one tool may not be accepted by another. Unknown arguments are rejected.

Use JSON numbers for numeric offsets. Comma-separated filters remain strings. The company search `hasJobs` argument is the string `"true"`; omit it for unrestricted results.

Each tool call performs one public operation and returns one result or page. Continue using the returned cursor or the public operation's offset parameters. There is no automatic pagination or retry. See [Pagination](https://docs.envoapi.com/guides/pagination.md) for operation-specific behavior.

## Results, Credits, and errors

`structuredContent` contains the same public response body as REST. Each tool's `outputSchema` describes its successful `data` and `meta` response. Successful results also include the body's JSON serialization in a text content block. Errors use a public error body and text recovery guidance rather than the success schema. Private provider fields are excluded by the same public projection used by REST.

The `_meta["envoapi.com/lookup"]` object contains:

* `status`: the corresponding public API HTTP status.
* `headers`: `X-Request-Id` and the applicable `X-Credits-Remaining`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` values. Reset and retry values use seconds, as in REST.

Tool calls share the account's REST RPM limit, Credit balance, pricing, and Usage Analytics. Contact lookup uses the existing contact settlement policy. Repeating a call, including a cached lookup or reusing a JSON-RPC `id`, starts another potentially billable operation. JSON-RPC IDs are correlation IDs, not idempotency keys.

Business failures return `isError: true` with the public error body and the corresponding public status in `_meta`. Invalid or expired credentials require authentication and can return HTTP 401 with an OAuth discovery challenge. A valid connection for a restricted account can list tools; account restrictions are reported as tool errors when a lookup is attempted. Access-service failures can use HTTP 503. Malformed protocol messages return protocol errors. See [Errors](https://docs.envoapi.com/guides/errors.md) for public error codes.

The normal 45-second lookup deadline applies. Disconnecting or cancelling in your client does not reverse an admitted operation: the server completes Credit settlement. If settlement is uncertain, `retryable` is false. Inspect your account's Usage Analytics before deciding whether to start another lookup.

## Tool catalog

The table lists identifier choices or required arguments. Optional filters and pagination fields are published by `tools/list` and documented in the corresponding Public v1 operation.

| Tool                               | Identifier choices or required arguments   |
| ---------------------------------- | ------------------------------------------ |
| `get_profile_details`              | Exactly one: `url`, `username`, `publicId` |
| `get_profile_contact`              | Exactly one: `url`, `username`             |
| `get_profile_full_experience`      | Exactly one: `url`, `username`             |
| `get_profile_education`            | Exactly one: `url`, `username`             |
| `get_profile_skills`               | Exactly one: `url`, `username`             |
| `get_profile_certifications`       | Exactly one: `url`, `username`             |
| `get_profile_courses`              | Exactly one: `url`, `username`             |
| `get_profile_company_interests`    | Exactly one: `url`, `username`, `publicId` |
| `get_profile_volunteer_experience` | Exactly one: `url`, `username`             |
| `get_company_details`              | Exactly one: `url`, `slug`, `publicId`     |
| `get_profile_posts`                | `username`                                 |
| `get_profile_comments`             | `username`                                 |
| `get_profile_reactions`            | `username`                                 |
| `get_similar_profiles`             | `username`                                 |
| `get_post`                         | Exactly one: `url`, `slug`                 |
| `get_post_comments`                | Exactly one: `url`, `slug`                 |
| `get_post_reactions`               | Exactly one: `url`, `slug`; `reactionType` |
| `get_company_posts`                | `slug`                                     |
| `get_similar_companies`            | Exactly one: `url`, `slug`                 |
| `get_company_people`               | `slug`                                     |
| `get_company_products`             | `slug`                                     |
| `get_company_jobs`                 | `slug`                                     |
| `search_companies_by_domain`       | `domain`                                   |
| `search_companies_by_keyword`      | `keywords`                                 |
| `search_schools_by_keyword`        | `keywords`                                 |
| `search_people_by_keyword`         | `keywords`                                 |
| `search_all_results_by_keyword`    | `keywords`                                 |
| `search_posts_by_hashtag`          | `hashtag`                                  |
| `search_posts_by_keyword`          | `keywords`                                 |
| `search_locations_by_keyword`      | `keywords`                                 |
| `search_industries_by_keyword`     | `query`                                    |
| `search_service_categories`        | None                                       |
| `get_search_typeahead`             | `query`                                    |
| `search_jobs`                      | `keywords`                                 |
| `get_job_details`                  | `url`                                      |

[Documentation index](https://docs.envoapi.com/llms.txt) · [All endpoints](https://docs.envoapi.com/api/index.md)