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.

  5. Create a campaign and add contacts to campaigns

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 1 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

You can connect SourceWhale to ChatGPT as a custom MCP server. Account and workspace policies apply to adding and using custom MCP servers.

ChatGPT plugins are available on web, desktop, and mobile when they are available to your account.

💡 Refresh SourceWhale tools

When we release new tools and you want to access them, open Settings > Plugins in ChatGPT on the web, or go straight to chatgpt.com/plugins, click into SourceWhale and select Refresh tools. Then start a new conversation.
​

Step 1: Add the custom MCP server

Open ChatGPT Plugins. Select the + button, then choose Add custom MCP server.

Step 2: Enter the connection details

Icon (optional): You can use the one attached.

Enter SourceWhale as the name and add a description.

Under Connection, enter the public MCP server URL, including the /mcp path: https://mcp.sourcewhale.app/mcp

Select Authentication as OAuth.

Review the risk warning and select I understand and want to continue.

Account and workspace access

In a managed workspace, administrators control plugin availability and MCP access for each role. Ask your workspace admin to check these settings if SourceWhale is not available to you.

Step 3: Complete setup

Sign in to SourceWhale, review the requested permissions, then grant access.

Start a new conversation. Type @ in the prompt box and select SourceWhale to use the plugin.

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 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. The cached version expires within 5 minutes. Retry after it expires.

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?"

Try that request. It matches against everything you hold on a person, including what they said on calls, not just their CV.

Building a campaign

  • "Find me the heads of engineering we already know in Berlin, and set up a campaign for them"

The assistant drafts the campaign with its steps and personalisation, then gives you a link to review the list in SourceWhale before anything goes out.

  • "Research these 20 companies, find their heads of talent, and write me a campaign that references what each of them is hiring for"

Your assistant can use what it finds online to personalise the outreach, then set up the campaign in SourceWhale for you to review.

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 a single view - "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?"

Checking your numbers

  • “How many first interviews did we book this week?”

  • “How am I tracking against my target this month?”

  • “What’s our CV to interview ratio on the Acme roles?”

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 choose a template 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, their steps 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.

Reports and targets

  • Ask for your CRM & ATS numbers: interviews booked and held, CVs sent, calls, candidates added, jobs created, offers, hires, revenue and days to fill

  • See how you’re tracking against your targets for the week, month or quarter

  • See your job and business development funnels, and the conversion rates between stages

  • Narrow any of it by period, by teammate or group, by client or by project

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.

  • Create manual to-dos for contacts. New to-dos are assigned to the connected SourceWhale user.

  • Add existing contacts to projects. New members of Job and Business Development projects enter the default pipeline status.

  • Create a campaign. The assistant returns a link so you can review it in SourceWhale. Creating a campaign doesn’t add anyone to it.

  • Add existing contacts to a campaign. The assistant prepares the list and returns a review link. You complete the usual review in SourceWhale before any campaign is sent.

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

Pipeline move notes: 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. Moving someone into an interview stage can create an interview without a date. You can add the date afterwards.

Tips for better results

  • Say SourceWhale in your first message. For ChatGPT, type @ and select SourceWhale to invoke it. In other assistants, mention SourceWhale by name.

  • 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".

  • Use ChatGPT on web, desktop, or mobile. Plugins are available on these surfaces when available to your account.

  • 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. In ChatGPT, start a new conversation, type @, and select SourceWhale. In other assistants, enable SourceWhale for the conversation and mention it by name.

  • You can't add SourceWhale in a managed ChatGPT workspace. Ask your workspace admin to check plugin availability and MCP access for your role.

  • A tool has stopped working, or something new isn't showing up. In ChatGPT, open the SourceWhale connection in ChatGPT Plugins and select Refresh. Confirm that the tool metadata changed, then start a new conversation. For other assistants, follow their instructions to refresh connected MCP tools.

  • A tool can't do something. Check the tool's permissions and confirm your SourceWhale account can access the requested data.

FAQs

Can I create several records in a single request?
Yes. In a single 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.
​

Can the assistant send outreach on my behalf?
No. It prepares everything for you but can't hit send. When you ask it to add contacts to a campaign, it prepares the list and gives you a link. Nothing is sent until you complete the review in SourceWhale yourself.
​

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