--- canonical: https://docs.jentic.com/guides/mcp/Local%20MCP/windsurf/ representation: markdown-alternate # Canonical page: https://docs.jentic.com/guides/mcp/Local%20MCP/windsurf/ # This is the Markdown alternate of the page above. title: "Local Jentic MCP Server in Windsurf (Deprecated)" description: >- Configure the local Jentic MCP server in Windsurf so you can search, load, and execute thousands of external APIs directly inside your Windsurf coding workflow. --- # Jentic MCP + Windsurf !!! warning "Deprecated" This page is **deprecated** and kept only for reference. It describes the retired hosted `app.jentic.com` platform and the `jentic-sdks` MCP plugin. To use Jentic over MCP today, see the [MCP overview](../remote-mcp.md) — search the API directory over the hosted MCP server, and connect your **self-hosted [Jentic One](../../../reference/jentic-one/index.md)** instance as a custom connector. > **Goal** — In a few minutes, you'll enable Jentic MCP tools in Windsurf, allowing you to **search**, **load**, and **execute** external APIs directly in your coding workflow. ## What you'll get With Jentic MCP configured in Windsurf, you'll gain access to powerful tools: ### Tools available | Tool available in Windsurf | What it does | |----------------------------|--------------| | **search_apis** | Type what you need (e.g., "Send Discord Message", "Find New York Times Articles") and MCP lists matching APIs. | | **load_execution_info** | See the details of any API you found - what information it needs and how to use it. | | **execute** | Actually use the API - provide the required information and get results back in the chat. | ## Before you start Ensure you have the following: | You need | Why | Quick install | |----------------------|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------| | **Python ≥ 3.11** | Required for uv/uvx and Jentic CLI. | [python.org](https://www.python.org/downloads/) | | **Windsurf** | The AI coding assistant where MCP tools run. | [Windsurf](https://windsurf.com/download) | | **uv / uvx** runtime | Launcher that runs the Jentic MCP server. | Install with pip: `pip install uv` (any OS)  **or**  with Homebrew (macOS): `brew install uv`
_If you have trouble with `uvx`, see [Making Windsurf See `uvx`](#making-windsurf-see-uvx) below._ | ## 1. Create an Agent & get your Agent API Key 1. Go to **[app.jentic.com/sign-in](https://app.jentic.com/sign-in)** and sign in to your account. 2. In **Credentials**, add any API secrets you'll use (e.g., Discord bot token, NYT key). These credentials will be securely stored in Jentic and automatically used by your agent. 3. Open **Agents → New Agent**, select which APIs/workflows this agent can access, then **Generate API Key**. * Keys are **scoped** to the APIs you selected and shown **once**. * **Recommended:** Store all API credentials in Jentic's Credentials section rather than using environment variables. 4. Set the Agent API Key as an environment variable so Windsurf can pass it to the MCP server: **macOS / Linux** ```bash export JENTIC_AGENT_API_KEY="" ``` **Windows (PowerShell)** ```powershell setx JENTIC_AGENT_API_KEY "" $env:JENTIC_AGENT_API_KEY = "" # current session ``` > ✅ No more `jentic register`, `curl`, or `JENTIC_UUID`. Use **`JENTIC_AGENT_API_KEY`** from the **Agents** page. ## 2. Configure Windsurf to use Jentic MCP 1. **Open Windsurf.** (If it's already running, you might still need to restart it later for changes to fully apply, but you can proceed with configuration.) 2. **Access your Windsurf MCP configuration file (`mcp_config.json`):** The easiest way to open (or create if it doesn't exist) your `mcp_config.json` is through the Windsurf interface: 1. **Via Windsurf's MCP Configuration UI (Recommended Method):** a. In Windsurf, click the MCP status icon (it might look like a hammer), as shown below: ![Accessing Windsurf MCP Configuration](assets/images/findMCPConfigure.png) b. From the menu that appears, select **"Configure"** (or a similarly named option like "Edit Configuration"). This action will directly open your `mcp_config.json` file in your default text editor. If you prefer, or if the UI method isn't available or you can't locate the icon, you can manually find and open the file. * **macOS:** `~/.codeium/windsurf/mcp_config.json` * Terminal: ```bash mkdir -p ~/.codeium/windsurf open ~/.codeium/windsurf/mcp_config.json ``` * Finder: ⇧⌘G → `~/.codeium/windsurf/` * **Linux:** Common locations: * `~/.config/Codeium/Windsurf/mcp_config.json` * `~/.codeium/windsurf/mcp_config.json` * Flatpak: `~/.var/app/com.codeium.windsurf/config/Codeium/Windsurf/mcp_config.json` * Terminal: ```bash xdg-open ~/.codeium/windsurf/mcp_config.json ``` * **Windows:** `%APPDATA%\Codeium\Windsurf\mcp_config.json` * File Explorer: paste `%APPDATA%\Codeium\Windsurf\` in the address bar, create the file if missing. * PowerShell: ```powershell notepad $env:APPDATA\Codeium\Windsurf\mcp_config.json ``` 3. **Add or update the Jentic MCP server configuration:** Paste the following JSON into your `mcp_config.json` file. * If the file is new or was empty (Windsurf might create an empty structure if you used the "Configure" option on a non-existent file), you can paste the entire block below, potentially replacing any minimal content Windsurf added. * If the file already contains an `mcpServers` object with other servers, carefully add the `"jentic": { ... }` entry within it, ensuring correct JSON formatting (e.g., add a comma before it if it's not the first server entry). ```jsonc { "mcpServers": { "jentic": { "command": "uvx", "args": [ "--from", "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp", "mcp" ], "env": { "JENTIC_AGENT_API_KEY": "" } } } } ``` 4. **Save** the `mcp_config.json` file. 5. **Restart Windsurf** for the changes to take full effect and load the Jentic MCP server. (Even if Windsurf opened the file for you, a restart is crucial after modifying the configuration.) ## 3. Managing API Credentials **Recommended approach:** Store all API credentials in Jentic's Credentials section when creating your agent. This keeps credentials secure and centralized. If you need to add credentials for APIs you want to use: 1. Go back to [app.jentic.com](https://app.jentic.com) and sign in. 2. Navigate to **Credentials** and add any additional API keys, tokens, or secrets needed. 3. Update your agent to include the new credentials, or create a new agent with the updated credentials. > **Note:** Only the `JENTIC_AGENT_API_KEY` should be set as an environment variable. All other API credentials should be stored in Jentic's Credentials section, not as environment variables in your MCP configuration. ### Optional: Using Environment Variables If you prefer to use environment variables directly instead of storing credentials in Jentic, you can add them to your MCP configuration: 1. Open the same `mcp_config.json` file. 2. Insert or update the **`env`** block *inside* the `jentic` server. 3. Save the file and restart Windsurf. **Example configuration with environment variables:** ```jsonc { "mcpServers": { "jentic": { "command": "uvx", "args": [ "--from", "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp", "mcp" ], "env": { "JENTIC_AGENT_API_KEY": "", "DISCORD_BOTTOKEN": "", "OPENAI_API_KEY": "" } } } } ``` > **Security tip:** The `mcp_config.json` file is plain text. Ensure it's stored securely, especially if it contains sensitive API keys. ## 4. If something doesn't work | What you see / Problem | Try this | | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Jentic MCP tools not available in Windsurf | Check `mcp_config.json` for JSON syntax errors (e.g., missing commas, incorrect brackets). Ensure Windsurf was fully restarted after any changes. Check Windsurf's logs for MCP-related errors. | | "command not found: uvx" (in logs or error) | `uvx` is not in a path Windsurf can see. See "Making Windsurf See `uvx`" below for details. | | API calls fail (e.g., 401/403 errors) | The API likely requires authentication. Use `/load_execution_info` to check its requirements, then add the necessary credentials to Jentic's Credentials section and ensure your agent has access to them. Restart Windsurf. | | Other errors from Jentic MCP tools | Check Windsurf's logs for more details. For advanced debugging, you can run the Jentic MCP server manually and inspect its direct output/logs. | --- ### Making Windsurf See `uvx` Windsurf, like many applications, might not automatically pick up binaries added to your shell's `PATH` via files like `.zshrc` or `.bashrc`. Choose **one** of these options: #### Option A – Homebrew / System package (macOS & Linux) * Homebrew (macOS) or your distro’s package manager / a `sudo pip install uv` drops `uvx` somewhere Windsurf already looks: * `/usr/local/bin` on Intel Macs & most Linux distros * `/opt/homebrew/bin` on Apple Silicon If `which uvx` returns a path, you’re good – skip this section. #### Option B – pip / pipx / pyenv (user-local installs) If `uvx` lives in a user-local directory, expose it via a **symlink** (macOS/Linux) or by **adding the folder to PATH** (Windows). * macOS / Linux – symlink ```bash sudo ln -sf "$(which uvx)" /usr/local/bin/uvx # use /opt/homebrew/bin on Apple Silicon sudo ln -sf "$(which uv)" /usr/local/bin/uv ``` * Windows – PATH 1. Locate the folder containing `uvx.exe` (e.g. `%USERPROFILE%\AppData\Roaming\Python\Python311\Scripts`). 2. Add that folder to *Path* in **Environment Variables…**. 3. Restart Windsurf (and any open terminals). #### Option C – Hard-code the full path Skip PATH tweaks entirely and set the absolute path to `uvx` / `uvx.exe` in the `command` field of `mcp_config.json`.