Skip to main content

Using the SourceWhale MCP Server

Learn how to connect AI assistants to SourceWhale and run your day-to-day from a conversation.

Overview

The SourceWhale MCP Server is a hosted connection for compatible AI assistants. It lets an AI assistant retrieve, edit, and add data in SourceWhale

Common use cases

  1. Handle recruiting tasks, such as client prep, candidate follow-up, pipeline updates and more directly from a chat conversation.

  2. Let your assistant read and write SourceWhale data for you.

  3. Combine SourceWhale with other tools for more complex, multi-step workflows.

How to set up

Connect to Claude

  1. On your Claude Desktop app, click the + button at the bottom-left of the chat, then click Add custom connector

  2. Add name and MCP Server URL and click Continue

    1. Name: SourceWhale

    2. MCP Server URL: https://mcp.sourcewhale.app/mcp

  3. You will get an "Add custom Connector" screen, leave the settings as default:

    • Authentication: Sign-in now

    • OAuth client: Use Claude's published Identity

    Scroll down and then click Add

  4. A new tab will open in your Browser. Click on Continue connecting

  5. You'll then be redirected to the SourceWhale consent screen:

    • Sign in to your SourceWhale account if you're not already signed in

    • Review the requested permissions and choose what it can Read and what it can Write to.

    • Grant Claude access to your SourceWhale account

  6. It should then show as "Connected" and you can click on "Open desktop app" to return to the desktop app.

  7. Navigate back to Claude and enable SourceWhale in your chat by toggling SourceWhale on by clicking on the + button -> Connectors -> Check if SourceWhale MCP is toggled ON.

Customise what Claude can do

  • Permissions are granted per tool, not all at once.

  • Read access and write access are controlled separately.

  • Write actions ask for confirmation before they run.

  • You can auto-approve any tool to skip the confirmation step.

How to use it:

  1. Open the Connectors menu in Settings.

  2. Select the SourceWhale connector.

  3. For each tool, choose Always allow, Need approval, or Blocked.

If you don't want Claude making any changes to your data, block the write tools and leave the rest enabled.

Connect to ChatGPT

To install a connector in ChatGPT, you'll need Developer Mode enabled.

We'd suggest doing the whole setup in your browser rather than the desktop app, as some desktop versions don't have Developer Mode at all. Once the connector is installed, you can use it everywhere: browser, desktop app and mobile.

💡 One thing to know about ChatGPT

It keeps the version of SourceWhale you first connected to. Each time we release new tools, you'll need to disconnect and reconnect the connector to pick them up.

Step 1: Turn on Developer Mode

On a personal account (Free, Plus, Pro)

  1. Click your profile at the bottom left, then Settings and Security and login.
    Or go straight to: https://chatgpt.com/#settings/Security

  2. Turn on Developer Mode


On a Business or Enterprise account

On a Business or Enterprise account

Developer Mode isn't in your personal settings by default, even if you're the account owner. A workspace admin needs to enable it at workspace level first, in the admin console, and grant access to the users who need it. Look under the workspace or member permissions settings rather than your own.

Once that's done, it appears under Settings > Security and login for the authorised users, and you can follow the steps above.

Step 2: Add the connector

3. Go to Plugins in the left sidebar
Or go straight to https://chatgpt.com/#settings/Plugins

4 .Then click Browse Plugins

5. Click the + in the top right and Click Create App
6. Click Create MCP App


​

7. Fill in the form:

  • Icon: optional, you can use the SourceWhale logo below

  • Name: SourceWhale

  • Description: optional

  • Connection: Server URL

  • Server URL: https://mcp.sourcewhale.app/mcp

  • Authentication: OAuth

8. Tick I understand and want to continue, then click Create.

9. You'll be redirected to the SourceWhale consent screen:

  • Sign in to your SourceWhale account if you're not already signed in

  • Review the requested permissions

  • Grant ChatGPT access to your SourceWhale account

10. Once the connector is installed, you can use it directly in your ChatGPT conversations. Click the + in the chat bar and select SourceWhale. You can also just mention SourceWhale in your message and it should pick it up on its own.

Connect SourceWhale to another MCP-compatible assistant

If your assistant supports remote MCP servers and OAuth, use these steps. Menu names differ between assistants.
​
1. Open the assistant’s integrations, connectors, or MCP settings.
2. Choose the option to add a remote or custom MCP server.
3. Enter SourceWhale as the name and https://mcp.sourcewhale.app/mcp as the server URL.
4. Select OAuth when asked how to authenticate.
5. Sign in to SourceWhale, review the requested permissions, and approve access.
6. Return to the assistant and enable SourceWhale for the conversation.
​

Connecting to an MCP that use a Client ID Metadata Document (CIMD)

Some MCP clients use a Client ID Metadata Document (CIMD) for OAuth. This can come up with a self-hosted OpenClaw instance, including one running on a VPS, or another custom or third-party MCP client that uses CIMD. It depends on your OAuth registration method. If you are not using a client that uses a CIMD, then you do not need this step.
​
​If your client uses CIMD:
1. Make its client metadata JSON available directly at a public HTTPS URL.
2. Add a top-level client_id field to that JSON. Its value must exactly match the URL where the JSON is hosted. For example:

json
"client_id": "https://client.example/.well-known/oauth-client-metadata.json"

Replace the example URL with the actual URL of your metadata document.
3. Configure the MCP client to send that same URL as its OAuth client_id. Keep the client’s callback URI in redirect_uris.
4. Use https://mcp.sourcewhale.app/mcp as the SourceWhale server/resource URL. The OAuth flow must use authorization code with S256 PKCE. With token_endpoint_auth_method set to none, no separate static client ID or client secret is required.
​
If consent shows “Unknown MCP client,” check that the metadata URL is publicly reachable over HTTPS and that its client_id exactly matches your public client metadata URL After changing the metadata, retry; it may take up to five minutes for the cached version to expire.

What can you do with SourceWhale MCP?

Before a call

  • "I'm speaking to Sarah Mitchell in 10 minutes, what do I need to know?"

Pulls her record, your previous calls and meetings with her, your notes, and the projects she's involved in. If she's a client contact, it picks up the roles you're working on for them too.

  • "What did Acme say about the salary band on our last call?"

Searches what was actually said on the call, not just what someone typed into a field afterwards.

After a call

  • "I've just finished a call with John Doe, summarise what he said about his notice period and package"

  • "Log that call on John's record with a summary"

  • "Update John's notice period to 3 months and move him to Interview on the Backend Engineer project"

If you use another notetaker, that is also connected to Claude, you can ask the assistant to push that summary into SourceWhale for you or update fields based on the summary.

Presenting candidates to a client

  • "Write up the 3 candidates on the Backend Engineer project for the hiring manager, using our branding"

It pulls their CVs, your interview notes and the project details, and writes it in your agency's format.

Searching your database

  • "Do we already have contacts at Acme, Globex and Initech?"

  • "Who have I spoken to about relocating to Berlin?"

  • "Here's a job description, who in our database would fit?"

That last one is worth trying properly. It matches against everything you hold on a person, including what they said on calls, not just their CV.

Answering candidate questions

  • "A candidate is asking whether the Backend Engineer role is fully remote and what the tech stack is, what do we know?"

Looks at the job description, your internal project notes, and the calls with the client where it was discussed.

Planning your day

  • Get your to-do list for the day in one place - "What are my tasks today?"

  • See who's interviewing and what meetings are on your calendar this week - "What interviews and meetings do I have this week?"

  • Know exactly who you need to call today - "Who do I need to call today?"

Everything it can do

The examples above give you a flavour. Here's the full picture, so you know where the edges are.

Reading your data

People and companies

  • Look up anyone in your database and see their full record, including custom fields

  • Search for people across your database

  • Find people based on what was said about them in calls, meetings, notes and their CV. This searches the actual content, not just names and fields

  • Look up and search companies

Calls and meetings

  • Pull up any call or meeting, including the full transcript

  • Search across your calls and meetings

  • See what meetings are scheduled

Projects

  • Look up a project, its job description and your internal project notes

  • Search your projects

  • See a project's pipeline structure, and where each person sits in it

  • See everyone on a project, and the client contacts attached to it

  • See scheduled interviews, on a project or across your week

Notes, tasks and campaigns

  • Search your campaigns and their tasks

  • See your campaign tasks, including anything overdue

  • See and search your manual to-dos

  • Read your notes, and search them by things like who they're about and when they were written

Files and branding

  • See what files are attached to a contact and download them, including CVs

  • Pull your agency's own branding details and assets, so client-facing documents can come out in your format

Changing your data

4 things, and each one asks for your confirmation before it runs

  • Create a note on a person or a company. You can log it as a general note, a phone call, an SMS, a meeting or an interview.

  • Edit a person's details. Name, school, location, salary, bonus, expected salary, notice period and relationship

  • Edit a person's custom fields. Text, number, date and multi-select fields

  • Move someone through a project pipeline. They need to already be on the project.

Two things worth knowing about pipeline moves. If your stage has an automated email set up, it won't be sent when the assistant moves someone. Do that move in SourceWhale if you want the email to go out. And moving someone into an interview stage can create an interview without a date on it, so you may want to add the date yourself afterwards.

Tips for better results

  • Say SourceWhale in your first message. The assistant usually works out on its own when to use it, but mentioning it makes sure.

  • Combine it with your other tools. If you've connected your email, calendar or Notion, you can chain things together: "find the answer in SourceWhale and draft the reply in my email", or "use my template in Notion to write this up".

  • It works on your phone. Both Claude and ChatGPT have mobile apps, so you can prep for a call from a taxi without opening SourceWhale.

  • Be specific about who and what. "Sarah Mitchell at Acme" works better than "that candidate I spoke to last week".

If something isn't working

  • The assistant isn't using SourceWhale. Check the connector is toggled on in your chat, then mention SourceWhale directly in your message.

  • You can't see the connector after adding it. On a company workspace, your administrator may need to approve it first.

  • A tool has stopped working, or something new isn't showing up. Your assistant is probably still on an older version of SourceWhale. Disconnect the SourceWhale connector and connect it again to get the latest one. This mostly happens on ChatGPT: it keeps the version of SourceWhale from the moment you connected, so anything we add afterwards doesn't appear on its own.

  • A tool says it can't do something. Check your permission settings, that tool may be blocked. It's also worth remembering it can only reach what your own SourceWhale account can reach.

Stuck or need some help? Click on the chat icon at the bottom right-hand corner to connect with our support team!

Related Articles
Did this answer your question?