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

Module access

Some tools require specific SourceWhale modules and connector permissions. Company, project and manual to-do tools require CRM & ATS. Campaign tools require Outreach. Call tools require Conversations access for your region or SourceWhale notetaker access. Meeting tools require SourceWhale notetaker access.

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.

  4. After a call, ask your assistant to create a contact and log a phone-call note on the contact record.

How to set up

Manage MCP access for your team

MCP access is enabled by default for new team members. If you are an admin, open Admin > MCP Access to control team access. Use the toggle beside a team member to turn MCP access on or off. Admin users always have MCP access.

Connect to Claude

Custom remote MCP connectors are available on Free, Pro, Max, Team, and Enterprise plans. Free accounts are limited to one custom connector. On an individual Free, Pro, or Max plan, add SourceWhale from Customize > Connectors, then choose + Add > Add custom connector.

For Team or Enterprise, an Owner or Primary Owner first adds SourceWhale under Organization settings > Connectors. Members then open Customize > Connectors, find SourceWhale, and click Connect.

  1. For individual accounts, open Customize > Connectors, choose + Add, then Add custom connector. Team and Enterprise members should use the organization connector their Owner or Primary Owner added.

  2. For individual accounts, enter the name and MCP Server URL shown below, then click Continue. An Owner or Primary Owner completes this step during organization setup.

    1. Name: SourceWhale

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

  3. Review the authentication settings. For SourceWhale, select Sign in now and Use Claude's published Identity.

    • 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. When SourceWhale shows as Connected, return to Claude.

  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

Note: If you do not see Developer mode as an option at all in your settings in ChatGPT then please navigate to the plugins page: https://chatgpt.com/plugins. Click on "Add"

and then click "Create MCP App" and then proceed with filling in the form.

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?

Working from a link

  • "Here's the link to a candidate in SourceWhale, what do we know about them?"

Paste a link to a person, company, project, campaign, call or completed meeting. The assistant picks up that exact record without searching by name.

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

  • See up to 10 recent notes, dialler calls and completed SourceWhale meetings on a contact's record, subject to your permissions.

  • With CRM & ATS, see a contact’s projects. With Outreach, see their campaigns.

Calls and meetings

  • Get summaries and full transcripts for completed calls and meetings you can access

  • 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 the pipeline templates available to you, then use one when creating a Job or Business Development project

  • 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

  • Look up a single campaign and see its details

  • 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

Tags

  • Find your team’s active tags by name.

  • Search for contacts using team tags.

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

  • If the assistant can't process a file directly, it can provide a download link that expires after 24 hours.

Changing your data

Your assistant can make these changes when your account and connector permissions allow them.

  • Create a contact. With CRM & ATS, use a company ID. Without CRM & ATS, enter a company name. SourceWhale stores that name as text on the contact.

  • Create companies and projects. This requires CRM & ATS access.

  • Create manual to-dos for contacts. This requires CRM & ATS access. New to-dos are assigned to the connected SourceWhale user.

  • Add existing contacts to projects. This requires CRM & ATS access. New members of Job and Business Development projects enter the default pipeline status.

  • Rename tags and add active tags to contacts and companies. MCP can't create new tags.

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

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

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

  • Move a contact through a project pipeline. The contact must 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.

FAQs

Can I create several records in one request?
Yes. In one request, you can ask your assistant to combine supported actions. For example, create a company, create a contact linked to it, create a project and add a manual to-do. You can also create multiple contacts or multiple companies at once. Company, project and manual to-do actions require CRM & ATS access.

What happens if a contact already exists?
When you ask SourceWhale MCP to create a contact, existing matches are returned without changing their records.

Does adding a contact to a project start outreach?
Adding an existing contact to a project through SourceWhale MCP does not start outreach.

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

Did this answer your question?

Related Articles