Get started

MCP quickstart

Give an AI client access to aVenture data
View as Markdown

The aVenture MCP server exposes the API as tools an AI client can call. The hosted server needs no install — point an OAuth-capable client at it and sign in. Self-hosting is for clients that cannot complete an OAuth flow.

Connect to the hosted server

Configure your client with:

SettingValue
URLhttps://mcp.aventure.vc/mcp
TransportStreamable HTTP
Client IDKL7mINzGk0le0QiD
Client secretnone — this is a public client

The client discovers the authorization server from the MCP endpoint and completes authorization code with PKCE. Dynamic client registration is disabled, so a client that accepts only a bare URL fails with Incompatible auth server: does not support dynamic client registration; the client ID above must be configured explicitly. In Claude Code that is an oauth block:

{
  "mcpServers": {
    "aventure": {
      "type": "http",
      "url": "https://mcp.aventure.vc/mcp",
      "oauth": {
        "clientId": "KL7mINzGk0le0QiD",
        "callbackPort": 6276
      }
    }
  }
}

Or claude mcp add --transport http --client-id KL7mINzGk0le0QiD --callback-port 6276 aventure https://mcp.aventure.vc/mcp. Other clients name these settings differently; what matters is that the client ID is set and the callback lands on /callback.

These redirect URIs are registered:

  • http://127.0.0.1/callback
  • http://localhost/callback
  • https://chatgpt.com/connector_platform_oauth_redirect
  • https://claude.ai/api/mcp/auth_callback

A loopback redirect may use any available port, such as http://127.0.0.1:6276/callback, as long as it keeps the /callback path. A client using a different callback path needs its own registered OAuth application — contact us to arrange one.

The endpoint answers OAuth protected-resource discovery, not an ordinary GET, so opening the URL in a browser is not a useful connectivity test. To exercise the flow without a client, run this in an interactive terminal, sign in to aVenture, and approve access — the Inspector exchanges the authorization code and lists the tools:

npx @modelcontextprotocol/[email protected] --cli \
  --server-url https://mcp.aventure.vc/mcp \
  --client-id KL7mINzGk0le0QiD \
  --callback-url http://127.0.0.1:6276/callback \
  --method tools/list

Verify the connection

Once the client is connected, call aventure_status. It returns the API status, the host it reached, and the MCP auth scope your credential actually carries — which is the one call that proves transport and credential together. Then call aventure_help to find the right tool and inputs for a given task.

The tool list reflects the permissions granted to the signed-in user, and the API checks permission again when an operation runs — a visible tool is not a guarantee that every call it can make will be authorized.

ToolWhat it does
aventure_statusReturn API status, host, and active MCP auth scope
aventure_helpFind the command for a task, with the inputs it needs
aventure_searchFind companies, people, news, or publications from a query
aventure_lookupTurn a name, URL, slug, ticker, or other identifier into the record that owns it
aventure_readRead one record, or the records attached to it
aventure_writeCreate a record, or change one that already exists
aventure_deleteRemove one record, or one link between records

Name the operation before you call it

The last five tools are thin wrappers over the API reference: each one runs an operation you name, so every call needs operationId, or method and path together. A call carrying only a query is rejected with Pass operationId or method+path.

aventure_help supplies the name. Ask in plain English and set resolve:

{ "q": "look up a company by name", "resolve": true }

It answers with one recommendation instead of a catalog. mcpTool names the tool to call, apiRoute gives the method and path, pathInput and queryInput and bodyInput list that operation’s argument names, and missingInputs lists the ones it will not run without. For the query above that is aventure_lookup and GET /v1/entities/lookup, so:

{ "operationId": "lookupEntity", "query": { "name": "Stripe" } }

That operation needs no credential, which makes it the shortest path to a first successful result.

The help parameter is q. On the other five tools query means the operation’s URL query parameters, and aventure_help ignores it. Help called with no q is not an error — it returns the head of the full catalog in no particular order.

Put each input where the help answer says it goes: pathInput values in pathParams, queryInput values in query, bodyInput values in body. Do not carry a shape between operations — entityId is a path parameter on the entity detail routes but a filter on GET /v1/entities, and GET /v1/entities/detail/fundraise-investor-joins calls it id.

responseFormat applies only to operations that declare a text/plain response. Setting it to text on a JSON-only operation sends Accept: text/plain, and the API answers 406. Leave it unset unless the operation offers both.

Self-host instead

Use this when your client configures MCP servers by URL but cannot run an OAuth flow, or when you want the server inside your own network.

The server requires Node.js 24.18 or later in the 24.x series.

npm install --global @aventurevc/mcp-server --registry=https://registry.npmjs.org/
aventure-mcp-server

It listens at http://localhost:3333/mcp. Leave it running while your client is connected. The server starts with no credential of its own — every request must carry a personal API key as a bearer token:

{
  "mcpServers": {
    "aventure": {
      "type": "http",
      "url": "http://localhost:3333/mcp",
      "headers": {
        "Authorization": "Bearer <personal-api-key>"
      }
    }
  }
}

Supply the key through your client’s own secret storage; its interpolation syntax differs by client. Never paste the key into a file you commit.

AVENTURE_MCP_PORT and AVENTURE_MCP_PATH change the listener — update the client URL to match. AVENTURE_MCP_JSON_LIMIT bounds the request body size.

This package speaks Streamable HTTP, not stdio. Configure a URL, not a command.

Next