Claude Desktop Setup

Overview

This guide walks you through configuring Claude Desktop to use f2d's job search tools. After setup, you can search for jobs by simply asking Claude in a conversation.

Time required: ~3 minutes

Step 1: Add the Configuration

Open the Claude Desktop MCP configuration file in your text editor:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following:

{
  "mcpServers": {
    "f2d": {
      "url": "<your-mcp-endpoint-url>"
    }
  }
}

Replace <your-mcp-endpoint-url> with the MCP endpoint URL provided to you.

Important notes:

• Only the url field is needed — no API key or extra headers
• If the file already has other MCP servers configured, add "f2d": { ... } inside the existing mcpServers object
• Make sure the JSON is valid (watch for missing commas between servers)

Step 2: Restart Claude Desktop

Fully quit Claude Desktop (not just close the window or minimize), then reopen it.

On first connection, your default browser will open a login page:

1. Register with your email (free) or sign in if you already have an account
2. After authentication, return to Claude Desktop

The MCP tool indicator should show that f2d is connected.

After the first login, subsequent connections authenticate automatically. You won't need to log in again unless your session expires.

Step 3: Verify the Setup

Follow these verification steps to confirm everything is working.

Verify Tool Discovery

In a Claude Desktop conversation, ask:

"What tools do you have available?"

Expected: Claude lists search_jobs and list_cities among its available tools.

Verify Search

Ask Claude:

"Find me machine learning engineer jobs in Seattle, show me the top 3"

Expected:

• Claude calls the search_jobs tool (you'll see a tool use indicator)
• Parameters include relevant query, city = "Seattle", top_k = 3
• Results appear as a formatted list with job title, company, salary, and more

The first search may take 5-10 seconds. This is normal — subsequent searches are faster.

Verify Tool Boundaries

Ask Claude something unrelated:

"What's the weather like today?"

Expected: Claude responds normally without calling any f2d tools. This confirms tools are only triggered when relevant.

Verification Checklist

Troubleshooting

Claude Desktop won't start after adding config

The JSON file likely has a syntax error. Common issues:

• Missing comma between MCP server entries
• Trailing comma after the last entry
• Mismatched brackets

Validate your JSON with a tool like jsonlint.com or your editor's JSON validation.

f2d not showing as connected

1. Make sure you fully quit and restarted Claude Desktop (not just closed the window)
2. Verify the endpoint URL is correct
3. Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Browser login page doesn't appear

1. Check that your default browser is set correctly
2. Verify the MCP endpoint URL is accessible from your network
3. Try opening the endpoint URL directly in your browser to test connectivity

Authentication fails

1. Wait a few seconds and try restarting Claude Desktop again
2. Clear your browser cookies for the login domain and try again
3. If you previously had an API key-based config, remove any headers field — OAuth doesn't use API keys

Searches return errors or timeout

1. First requests may take 5-10 seconds due to cold start — wait and retry
2. If errors persist, check your network connection
3. For Rate limit exceeded errors, wait a moment before the next search

Next Steps

• Learn about MCP concepts and architecture
• See JSON-RPC Examples for manual testing with curl
• Try the CLI as an alternative interface