|
| 1 | +# Perplexity TypeScript MCP Server |
| 2 | + |
| 3 | +It is generated with [Stainless](https://www.stainless.com/). |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +### Direct invocation |
| 8 | + |
| 9 | +You can run the MCP Server directly via `npx`: |
| 10 | + |
| 11 | +```sh |
| 12 | +export PERPLEXITY_API_KEY="My API Key" |
| 13 | +npx -y @perplexity-ai/perplexity_ai-mcp@latest |
| 14 | +``` |
| 15 | + |
| 16 | +### Via MCP Client |
| 17 | + |
| 18 | +There is a partial list of existing clients at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients). If you already |
| 19 | +have a client, consult their documentation to install the MCP server. |
| 20 | + |
| 21 | +For clients with a configuration JSON, it might look something like this: |
| 22 | + |
| 23 | +```json |
| 24 | +{ |
| 25 | + "mcpServers": { |
| 26 | + "perplexity_ai_perplexity_ai_api": { |
| 27 | + "command": "npx", |
| 28 | + "args": ["-y", "@perplexity-ai/perplexity_ai-mcp", "--client=claude", "--tools=all"], |
| 29 | + "env": { |
| 30 | + "PERPLEXITY_API_KEY": "My API Key" |
| 31 | + } |
| 32 | + } |
| 33 | + } |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +## Exposing endpoints to your MCP Client |
| 38 | + |
| 39 | +There are two ways to expose endpoints as tools in the MCP server: |
| 40 | + |
| 41 | +1. Exposing one tool per endpoint, and filtering as necessary |
| 42 | +2. Exposing a set of tools to dynamically discover and invoke endpoints from the API |
| 43 | + |
| 44 | +### Filtering endpoints and tools |
| 45 | + |
| 46 | +You can run the package on the command line to discover and filter the set of tools that are exposed by the |
| 47 | +MCP Server. This can be helpful for large APIs where including all endpoints at once is too much for your AI's |
| 48 | +context window. |
| 49 | + |
| 50 | +You can filter by multiple aspects: |
| 51 | + |
| 52 | +- `--tool` includes a specific tool by name |
| 53 | +- `--resource` includes all tools under a specific resource, and can have wildcards, e.g. `my.resource*` |
| 54 | +- `--operation` includes just read (get/list) or just write operations |
| 55 | + |
| 56 | +### Dynamic tools |
| 57 | + |
| 58 | +If you specify `--tools=dynamic` to the MCP server, instead of exposing one tool per endpoint in the API, it will |
| 59 | +expose the following tools: |
| 60 | + |
| 61 | +1. `list_api_endpoints` - Discovers available endpoints, with optional filtering by search query |
| 62 | +2. `get_api_endpoint_schema` - Gets detailed schema information for a specific endpoint |
| 63 | +3. `invoke_api_endpoint` - Executes any endpoint with the appropriate parameters |
| 64 | + |
| 65 | +This allows you to have the full set of API endpoints available to your MCP Client, while not requiring that all |
| 66 | +of their schemas be loaded into context at once. Instead, the LLM will automatically use these tools together to |
| 67 | +search for, look up, and invoke endpoints dynamically. However, due to the indirect nature of the schemas, it |
| 68 | +can struggle to provide the correct properties a bit more than when tools are imported explicitly. Therefore, |
| 69 | +you can opt-in to explicit tools, the dynamic tools, or both. |
| 70 | + |
| 71 | +See more information with `--help`. |
| 72 | + |
| 73 | +All of these command-line options can be repeated, combined together, and have corresponding exclusion versions (e.g. `--no-tool`). |
| 74 | + |
| 75 | +Use `--list` to see the list of available tools, or see below. |
| 76 | + |
| 77 | +### Specifying the MCP Client |
| 78 | + |
| 79 | +Different clients have varying abilities to handle arbitrary tools and schemas. |
| 80 | + |
| 81 | +You can specify the client you are using with the `--client` argument, and the MCP server will automatically |
| 82 | +serve tools and schemas that are more compatible with that client. |
| 83 | + |
| 84 | +- `--client=<type>`: Set all capabilities based on a known MCP client |
| 85 | + |
| 86 | + - Valid values: `openai-agents`, `claude`, `claude-code`, `cursor` |
| 87 | + - Example: `--client=cursor` |
| 88 | + |
| 89 | +Additionally, if you have a client not on the above list, or the client has gotten better |
| 90 | +over time, you can manually enable or disable certain capabilities: |
| 91 | + |
| 92 | +- `--capability=<name>`: Specify individual client capabilities |
| 93 | + - Available capabilities: |
| 94 | + - `top-level-unions`: Enable support for top-level unions in tool schemas |
| 95 | + - `valid-json`: Enable JSON string parsing for arguments |
| 96 | + - `refs`: Enable support for $ref pointers in schemas |
| 97 | + - `unions`: Enable support for union types (anyOf) in schemas |
| 98 | + - `formats`: Enable support for format validations in schemas (e.g. date-time, email) |
| 99 | + - `tool-name-length=N`: Set maximum tool name length to N characters |
| 100 | + - Example: `--capability=top-level-unions --capability=tool-name-length=40` |
| 101 | + - Example: `--capability=top-level-unions,tool-name-length=40` |
| 102 | + |
| 103 | +### Examples |
| 104 | + |
| 105 | +1. Filter for read operations on cards: |
| 106 | + |
| 107 | +```bash |
| 108 | +--resource=cards --operation=read |
| 109 | +``` |
| 110 | + |
| 111 | +2. Exclude specific tools while including others: |
| 112 | + |
| 113 | +```bash |
| 114 | +--resource=cards --no-tool=create_cards |
| 115 | +``` |
| 116 | + |
| 117 | +3. Configure for Cursor client with custom max tool name length: |
| 118 | + |
| 119 | +```bash |
| 120 | +--client=cursor --capability=tool-name-length=40 |
| 121 | +``` |
| 122 | + |
| 123 | +4. Complex filtering with multiple criteria: |
| 124 | + |
| 125 | +```bash |
| 126 | +--resource=cards,accounts --operation=read --tag=kyc --no-tool=create_cards |
| 127 | +``` |
| 128 | + |
| 129 | +## Running remotely |
| 130 | + |
| 131 | +Launching the client with `--transport=http` launches the server as a remote server using Streamable HTTP transport. The `--port` setting can choose the port it will run on, and the `--socket` setting allows it to run on a Unix socket. |
| 132 | + |
| 133 | +Authorization can be provided via the `Authorization` header using the Bearer scheme. |
| 134 | + |
| 135 | +Additionally, authorization can be provided via the following headers: |
| 136 | +| Header | Equivalent client option | Security scheme | |
| 137 | +| ---------------------- | ------------------------ | --------------- | |
| 138 | +| `x-perplexity-api-key` | `apiKey` | HTTPBearer | |
| 139 | + |
| 140 | +A configuration JSON for this server might look like this, assuming the server is hosted at `http://localhost:3000`: |
| 141 | + |
| 142 | +```json |
| 143 | +{ |
| 144 | + "mcpServers": { |
| 145 | + "perplexity_ai_perplexity_ai_api": { |
| 146 | + "url": "http://localhost:3000", |
| 147 | + "headers": { |
| 148 | + "Authorization": "Bearer <auth value>" |
| 149 | + } |
| 150 | + } |
| 151 | + } |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +The command-line arguments for filtering tools and specifying clients can also be used as query parameters in the URL. |
| 156 | +For example, to exclude specific tools while including others, use the URL: |
| 157 | + |
| 158 | +``` |
| 159 | +http://localhost:3000?resource=cards&resource=accounts&no_tool=create_cards |
| 160 | +``` |
| 161 | + |
| 162 | +Or, to configure for the Cursor client, with a custom max tool name length, use the URL: |
| 163 | + |
| 164 | +``` |
| 165 | +http://localhost:3000?client=cursor&capability=tool-name-length%3D40 |
| 166 | +``` |
| 167 | + |
| 168 | +## Importing the tools and server individually |
| 169 | + |
| 170 | +```js |
| 171 | +// Import the server, generated endpoints, or the init function |
| 172 | +import { server, endpoints, init } from "@perplexity-ai/perplexity_ai-mcp/server"; |
| 173 | + |
| 174 | +// import a specific tool |
| 175 | +import createChatCompletions from "@perplexity-ai/perplexity_ai-mcp/tools/chat/completions/create-chat-completions"; |
| 176 | + |
| 177 | +// initialize the server and all endpoints |
| 178 | +init({ server, endpoints }); |
| 179 | + |
| 180 | +// manually start server |
| 181 | +const transport = new StdioServerTransport(); |
| 182 | +await server.connect(transport); |
| 183 | + |
| 184 | +// or initialize your own server with specific tools |
| 185 | +const myServer = new McpServer(...); |
| 186 | + |
| 187 | +// define your own endpoint |
| 188 | +const myCustomEndpoint = { |
| 189 | + tool: { |
| 190 | + name: 'my_custom_tool', |
| 191 | + description: 'My custom tool', |
| 192 | + inputSchema: zodToJsonSchema(z.object({ a_property: z.string() })), |
| 193 | + }, |
| 194 | + handler: async (client: client, args: any) => { |
| 195 | + return { myResponse: 'Hello world!' }; |
| 196 | + }) |
| 197 | +}; |
| 198 | + |
| 199 | +// initialize the server with your custom endpoints |
| 200 | +init({ server: myServer, endpoints: [createChatCompletions, myCustomEndpoint] }); |
| 201 | +``` |
| 202 | + |
| 203 | +## Available Tools |
| 204 | + |
| 205 | +The following tools are available in this MCP server. |
| 206 | + |
| 207 | +### Resource `chat.completions`: |
| 208 | + |
| 209 | +- `create_chat_completions` (`write`): Generate a chat completion response for the given conversation. |
| 210 | + |
| 211 | +### Resource `async.chat.completions`: |
| 212 | + |
| 213 | +- `create_chat_async_completions` (`write`): Submit an asynchronous chat completion request. |
| 214 | +- `list_chat_async_completions` (`read`): Retrieve a list of all asynchronous chat completion requests for a given user. |
| 215 | +- `get_chat_async_completions` (`read`): Retrieve the response for a given asynchronous chat completion request. |
| 216 | + |
| 217 | +### Resource `search`: |
| 218 | + |
| 219 | +- `create_search` (`write`): Search the web and retrieve relevant web page contents. |
![stainless-app[bot]](https://avatars.githubusercontent.com/in/378072?v=4&size=40){kind=avatar}
0 commit comments