Skip to content

Commit 2da951b

Browse files
ikhareConvex, Inc.
ikhare
authored and
Convex, Inc.
committed
docs: Add mcp instructions (#35004)
GitOrigin-RevId: d051c1f1549e4e623e7620952754863a7fe2303e
1 parent 847eba3 commit 2da951b

File tree

7 files changed

+164
-15
lines changed

7 files changed

+164
-15
lines changed

‎npm-packages/docs/docs/ai.mdx

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -31,22 +31,22 @@ guarantees prevent common failure modes.
3131
AI code generation is most effective when you provide it with a set of rules to
3232
follow.
3333

34-
If you're using Cursor, add the model specific `.mdc` files in your project's
35-
`.cursor/rules/` directory.
34+
If you're using Cursor, add the `.mdc` files in your project's `.cursor/rules/`
35+
directory:
3636

3737
- [Convex Cursor Rules](https://convex.link/convex_rules.mdc)
3838

39-
<video
40-
src="/video/showing_where_to_put_convex_rules.mp4"
41-
autoPlay
42-
loop
43-
controls
44-
></video>
45-
46-
For all other IDEs, you can add the following to your rules or memories.
39+
For all other IDEs, add the following rules file to your project and refer to it
40+
when prompting for changes:
4741

4842
- [Convex Rules](https://convex.link/convex_rules.txt)
4943

5044
We're constantly working on improving the quality of these rules for Convex by
5145
using rigorous evals. You can help by
5246
[contributing to our evals repo](https://github.com/get-convex/convex-evals).
47+
48+
## Convex MCP Server
49+
50+
[Setup the Convex MCP server](/docs/ai/convex-mcp-server.mdx) to give your AI
51+
coding agent access to the your Convex deployment to query and optimize your
52+
project.

‎npm-packages/docs/docs/ai/convex-mcp-server.mdx

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Convex MCP Server"
3+
sidebar_position: 300
4+
description: "Convex MCP server"
5+
---
6+
7+
The Convex
8+
[Model Context Protocol](https://docs.cursor.com/context/model-context-protocol)
9+
(MCP) server provides several tools that allow AI agents to interact with your
10+
Convex deployment.
11+
12+
## Setup
13+
14+
Add the following command to your MCP servers configuration:
15+
16+
`npx -y convex@latest mcp start`
17+
18+
See editor specific instructions:
19+
20+
- [Cursor](/docs/ai/using-cursor.mdx#setup-the-convex-mcp-server)
21+
- [Windsurf](/docs/ai/using-windsurf.mdx#setup-the-convex-mcp-server)
22+
23+
## Available Tools
24+
25+
### Deployment Tools
26+
27+
- **`status`**: Queries available deployments and returns a deployment selector
28+
that can be used with other tools. This is typically the first tool you'll use
29+
to establish a connection with your deployment.
30+
31+
### Table Tools
32+
33+
- **`tables`**: Lists all tables in a deployment along with their:
34+
35+
- Declared schemas (if present)
36+
- Inferred schemas (automatically tracked by Convex)
37+
- Table names and metadata
38+
39+
- **`data`**: Allows pagination through documents in a specified table.
40+
41+
- **`runOneoffQuery`**: Enables writing and executing sandboxed JavaScript
42+
queries against your deployment's data. These queries are read-only and cannot
43+
modify the database.
44+
45+
### Function Tools
46+
47+
- **`functionSpec`**: Provides metadata about all deployed functions, including:
48+
49+
- Function types
50+
- Visibility settings
51+
- Interface specifications
52+
53+
- **`run`**: Executes deployed Convex functions with provided arguments.
54+
55+
### Environment Variable Tools
56+
57+
- **`envList`**: Lists all environment variables for a deployment
58+
- **`envGet`**: Retrieves the value of a specific environment variable
59+
- **`envSet`**: Sets a new environment variable or updates an existing one
60+
- **`envRemove`**: Removes an environment variable from the deployment
61+
62+
[Read more about how to use the Convex MCP Server](https://stack.convex.dev/convex-mcp-server)

‎npm-packages/docs/docs/ai/using-cursor.mdx

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Using Cursor with Convex"
3-
sidebar_position: 120
3+
sidebar_position: 100
44
description: "Tips and best practices for using Cursor with Convex"
55
slug: "using-cursor"
66
---
@@ -27,7 +27,36 @@ We're constantly working on improving the quality of these rules for Convex by
2727
using rigorous evals. You can help by
2828
[contributing to our evals repo](https://github.com/get-convex/convex-evals).
2929

30-
## Install and run Convex yourself
30+
## Setup the Convex MCP Server
31+
32+
The Convex CLI comes with a
33+
[Convex Model Context Protocol](/docs/ai/convex-mcp-server.mdx) (MCP) server
34+
built in. The Convex MCP server gives your AI coding agent access to the your
35+
Convex deployment to query and optimize your project.
36+
37+
To get started with Cursor, open "Cursor Settings > MCP", click on "Add new MCP
38+
server", and add a "convex" command server with the following CLI command:
39+
40+
`npx -y convex@latest mcp start`
41+
42+
After adding the server, ensure the "convex" server is enabled and lit up green
43+
(you may need to click "Disabled" to enable it). Here are what my Cursor
44+
Settings look like:
45+
46+
![Chat UI](/img/cursor-with-convex/convex_mcp_setup.webp)
47+
48+
If you're running into issues, confirm you're using Cursor version **0.46.8** or
49+
later (check under "Cursor > About Cursor" on macOS).
50+
51+
Now start asking it questions like:
52+
53+
- Evaluate and convex schema and suggest improvements
54+
- What are this app's public endpoints?
55+
- Run the `my_convex_function` query
56+
57+
## Tips and tricks
58+
59+
### Install and run Convex yourself
3160

3261
Keeping Convex running is crucial because
3362
[it automatically generates](https://docs.convex.dev/cli#run-the-convex-dev-server)
@@ -37,7 +66,7 @@ since it can't access the types for the queries and mutations it created.
3766
We recommended that you install (`npm install convex`) and run convex
3867
(`npx convex dev`) yourself in a terminal window.
3968

40-
## Keep your requests small
69+
### Keep your requests small
4170

4271
The best results when using agentic LLMs can be found when keeping the amount of
4372
changes you want to make small and git commit frequently. This lets you be more
@@ -48,7 +77,7 @@ After each successful prompt or series of prompts it is a good idea to commit
4877
your changes so that its simple to rollback to that point should the next prompt
4978
cause issues.
5079

51-
## Update and reference your `README.md`
80+
### Update and reference your `README.md`
5281

5382
The agent needs context about the specific business goals for your project.
5483
While it can infer some details from the files it reads, this becomes more
@@ -62,7 +91,7 @@ comprehensive README.md file in your project root and reference it.
6291
Product Requirements Document (PRD), this may be a good idea for more complex
6392
projects.
6493

65-
## Add Convex docs
94+
### Add Convex docs
6695

6796
Adding Convex docs can let you specifically refer to Convex features when
6897
building your app.

‎npm-packages/docs/docs/ai/using-windsurf.mdx

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: "Using Windsurf with Convex"
3+
sidebar_position: 200
4+
description: "Tips and best practices for using Windsurf with Convex"
5+
slug: "using-windsurf"
6+
---
7+
8+
[Windsurf](https://codeium.com/windsurf), the AI code editor, makes it easy to
9+
write and maintain apps built with Convex. Let's walk through how to setup
10+
Windsurf for the best possible results with Convex.
11+
12+
## Add Convex Rules
13+
14+
Add the following rules file to your project and refer to it directly when
15+
prompting for changes:
16+
17+
- [Convex Rules](https://convex.link/convex_rules.txt)
18+
19+
We're constantly working on improving the quality of these rules for Convex by
20+
using rigorous evals. You can help by
21+
[contributing to our evals repo](https://github.com/get-convex/convex-evals).
22+
23+
## Setup the Convex MCP Server
24+
25+
The Convex CLI comes with a
26+
[Convex Model Context Protocol](/docs/ai/convex-mcp-server.mdx) (MCP) server
27+
built in. The Convex MCP server gives your AI coding agent access to the your
28+
Convex deployment to query and optimize your project.
29+
30+
To get started with Windsurf, open "Windsurf Settings > Cascade > Model Context
31+
Protocol (MCP) Servers", click on "Add Server", click "Add custom server", and
32+
add the following configuration for Convex.
33+
34+
```json
35+
{
36+
"mcpServers": {
37+
"convex": {
38+
"command": "npx",
39+
"args": ["-y", "convex@latest", "mcp", "start"]
40+
}
41+
}
42+
}
43+
```
44+
45+
After adding the server return to the "Windsurf Settings > Cascade > Model
46+
Context Protocol (MCP) Servers" screen an click "Refresh" button for Windsurf to
47+
pick up the new server.
48+
49+
Once this is done you should see the Convex tool listed in the servers:
50+
51+
![Chat UI](/img/windsurf-with-convex/windsurf_convex_mcp.png)
52+
53+
Now start asking it questions like:
54+
55+
- Evaluate and convex schema and suggest improvements
56+
- What are this app's public endpoints?
57+
- Run the `my_convex_function` query

‎npm-packages/docs/docs/cspell.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@
6363
"OIDC",
6464
"OLAP",
6565
"OLTP",
66+
"Oneoff",
6667
"OpenAI",
6768
"OWASP",
6869
"pseudocode",

‎npm-packages/docs/static/img/cursor-with-convex/convex_mcp_setup.webp

16.9 KB
Binary file not shown.

‎npm-packages/docs/static/img/windsurf-with-convex/windsurf_convex_mcp.png

38.3 KB
Loading

0 commit comments

Comments
 (0)