Jentic MCP + Windsurf¶

Goal — In a few minutes, you’ll enable Jentic MCP tools in Windsurf, allowing you to find, inspect, and run external APIs directly in your coding workflow.

What you’ll get¶

With Jentic MCP configured in Windsurf, you'll gain access to powerful tools:

Before you start¶

Ensure you have the following:

1. Create an Agent & get your Agent API Key¶

1. Go to https://jentic.com/register and create an account (free).
2. In Credentials, add any API secrets you’ll use (e.g., Discord bot token, NYT key).

3. Open Agents → New Agent, select which APIs/workflows this agent can access, then Generate API Key.

4. Keys are scoped to the APIs you selected and shown once.

5. Set it as an environment variable so Claude can pass it to the MCP server:

macOS / Linux

export JENTIC_AGENT_API_KEY="<your-agent-api-key>"

Windows (PowerShell)

setx JENTIC_AGENT_API_KEY "<your-agent-api-key>"
$env:JENTIC_AGENT_API_KEY = "<your-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:

      

      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:

       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:

       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:

       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).

{
  "mcpServers": {
    "jentic": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp",
        "mcp"
      ],
      "env": {
        "JENTIC_AGENT_API_KEY": "<your-agent-api-key>"
      }
    }
  }
}

1. Save the mcp_config.json file.
2. 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. (Optional) Add API keys and Environment Variables¶

Some APIs discovered via /search_apis and inspected with /load_execution_info will require API keys, tokens, or specific base URLs. You can add these as environment variables in your Windsurf MCP configuration so they are automatically available to the Jentic MCP server.

Steps¶

1. Open the same ~/.codeium/windsurf/mcp_config.json file.
2. Insert or update the env block inside the jentic server configuration.
3. Save the file and restart Windsurf.

Full example after adding keys¶

{
  "mcpServers": {
    "jentic": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp",
        "mcp"
      ],
      "env": {
        "JENTIC_AGENT_API_KEY": "<your-agent-api-key>",
        "DISCORD_BOTTOKEN": "<your-discord-bot-token>",
        "OPENAI_API_KEY": "<your-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¶

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

  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.

Contact Us Next