Skip to content

Use obsei from your AI tool

Every tool runs the same local MCP server over stdio:

Terminal window
uvx --from "obsei>=1.0" obsei mcp

uvx comes with uv. The >=1.0 floor stops uvx from reusing an older cached obsei, such as a release candidate. The first start downloads obsei, so give the server a startup timeout of about 60 seconds where the tool has one.

The server reads obsei.yaml in the working directory, or the file named by OBSEI_CONFIG. Set OBSEI_DB for a database somewhere else and OBSEI_DB_KEY when it is encrypted. It opens the store read-only, except to queue agent proposals for approval (MCP). The plugins for Claude Code, Codex, Copilot, VS Code and Gemini also add the voice-of-customer skill: one SKILL.md shared by all of them.

Install in Cursor Install in VS Code

obsei isn’t listed in any tool’s official plugin directory yet. The plugin installs below come straight from this GitHub repository, which each tool accepts as a custom marketplace or source.

Checked on 15 October 2026 with Claude Code 2.1.300, Codex 0.146.0, the Copilot CLI 1.0.3 and Gemini CLI 0.64.0. The other rows follow each tool’s documented MCP setup and have not been tested by the maintainers; report an issue if one doesn’t work.

Tool Install Notes
Claude Code /plugin install obsei --marketplace obsei/obsei MCP server and skill. Older versions: /plugin marketplace add obsei/obsei, then /plugin install obsei@obsei
Codex codex plugin marketplace add obsei/obsei, then codex plugin add obsei@obsei MCP server and skill. MCP only: below
GitHub Copilot CLI copilot plugin install obsei/obsei:integrations/claude/obsei MCP server and skill
VS Code button above, or code --add-mcp '{"name":"obsei","command":"uvx","args":["--from","obsei>=1.0","obsei","mcp"]}' Copilot agent mode. MCP server. For the skill too, run Chat: Install Plugin From Source with https://github.com/obsei/obsei
Cursor button above MCP server only. The plugin with the skill has been submitted to the Cursor Marketplace and is not available there yet
Gemini CLI gemini extensions install https://github.com/obsei/obsei Asks for OBSEI_CONFIG, OBSEI_DB and OBSEI_DB_KEY; Gemini passes only these to the server
Antigravity agy plugin import gemini Imports the Gemini CLI extension above
Claude Desktop JSON config in claude_desktop_config.json
Cline ask Cline to install https://github.com/obsei/obsei It follows llms-install.md. Not in the Cline MCP Marketplace yet
Devin Desktop JSON config in ~/.config/devin/mcp_config.json Formerly Windsurf
Zed Zed settings
JetBrains AI Assistant Settings > Tools > AI Assistant > Model Context Protocol (MCP), Add, paste the JSON config
Junie JSON config in .junie/mcp/mcp.json
Kiro JSON config in .kiro/settings/mcp.json
Goose Install in Goose Or goose configure, Add Extension, Command-line Extension with the command above
ChatGPT Secure MCP Tunnel Private use only

Most tools take the same mcpServers block:

{
"mcpServers": {
"obsei": {
"command": "uvx",
"args": ["--from", "obsei>=1.0", "obsei", "mcp"],
"env": { "OBSEI_CONFIG": "/path/to/obsei.yaml", "OBSEI_DB_KEY": "..." }
}
}
}

VS Code’s .vscode/mcp.json uses servers in place of mcpServers.

Terminal window
codex mcp add obsei --env OBSEI_CONFIG=/path/to/obsei.yaml -- uvx --from "obsei>=1.0" obsei mcp

Then raise the startup timeout in ~/.codex/config.toml, and forward the database key from your environment rather than writing it to the file:

[mcp_servers.obsei]
command = "uvx"
args = ["--from", "obsei>=1.0", "obsei", "mcp"]
env = { OBSEI_CONFIG = "/path/to/obsei.yaml" }
env_vars = ["OBSEI_DB_KEY"]
startup_timeout_sec = 60

In settings.json:

{
"context_servers": {
"obsei": {
"command": "uvx",
"args": ["--from", "obsei>=1.0", "obsei", "mcp"],
"env": { "OBSEI_CONFIG": "/path/to/obsei.yaml" }
}
}
}

ChatGPT does not run local stdio servers. Its connectors need a public HTTPS MCP server with OAuth 2.1 (or no authentication) and reject static bearer tokens, so obsei serve with OBSEI_API_TOKEN cannot be added. obsei does not provide an OAuth server yet.

For private use in your own workspace, OpenAI’s Secure MCP Tunnel wraps obsei mcp with an outbound-only connection. Create a tunnel in Platform tunnel settings, download tunnel-client, then:

Terminal window
export CONTROL_PLANE_API_KEY="sk-..."
tunnel-client init --sample sample_mcp_stdio_local --profile obsei \
--tunnel-id tunnel_... --mcp-command 'uvx --from "obsei>=1.0" obsei mcp'
tunnel-client run --profile obsei

In ChatGPT, open Plugins, select +, Add custom MCP server, choose Tunnel under Connection and pick the tunnel. Keep tunnel-client run running while you use it. Records leave your machine for OpenAI as each tool returns them, already redacted.

For tools that connect over HTTP with a header, obsei serve serves the same tools at /mcp; see MCP and agents.