Muse connector
Use Deep Search from Meta's Muse: OAuth, lookups, status checks and the restricted research mode.
Deep Search's connector for Meta's Muse is a separate MCP server with 9 tools. It researches people, companies and vehicles from public sources and returns cited results, always in the restricted Muse research mode described below. Lookups run as jobs: a start tool waits up to 20 seconds, then hands back a lookup_id that get_lookup collects.
https://deepsearch.app/api/mcp/musehttps://deepsearch.app/.well-known/oauth-protected-resource/api/mcp/museConnect from Muse
- Once Deep Search is listed in Muse, open Settings → Connectors and choose Deep Search.
- Until then, add a custom connector in Muse with the endpoint https://deepsearch.app/api/mcp/muse.
- When Muse opens Deep Search's consent screen, sign in, choose Full access or Read only, and approve.
- To disconnect, remove the connector in Muse, or choose Disconnect under Developers → Integrations → Connected apps on deepsearch.app. Disconnecting revokes the connection's tokens and stops its running lookups.
Authentication
Muse signs in with OAuth 2.1: the authorization code flow with PKCE, S256 only. It can register through dynamic client registration or a client ID metadata document, and Meta's redirect URI is https://agent.meta.ai/api/hatch/oauth/callback. Tokens are bound to this endpoint. The consent screen offers two levels of access.
| Choice | Scopes | Allows |
|---|---|---|
| Full access | search dossier chat history:read | Start, read, list and cancel lookups. |
| Read only | history:read | Read and list lookups already started from Muse. Can't start or cancel one. |
| Scope | Tools | Granted by |
|---|---|---|
search | start_people_search, start_company_search | Full access |
dossier | start_person_report, start_company_report, start_vehicle_report | Full access |
chat | start_person_question | Full access |
history:read | get_lookup, list_lookups. Every lookup scope allows these too. | Full access and Read only |
cancel_lookup needs the scope of the lookup it stops, so a Read only connection can't cancel one.
Access tokens last 1 hour. Refresh tokens last 60 days and rotate on every use; presenting one that was already used revokes the connection. An expired or revoked token gets 401 with a WWW-Authenticate challenge that points at the protected-resource metadata above.
Tools
Meta classes every Muse connector tool as Read, Write or Sensitive write.
| Class | Meaning | Tools |
|---|---|---|
| Read | Returns what the account already has. No side effects, and never uses usage. | get_lookup, list_lookups |
| Write | Starts or stops work for the connected account and may use its included usage. Nothing is bought, sent, posted or shared. | start_people_search, start_person_report, start_person_question, start_company_search, start_company_report, start_vehicle_report, cancel_lookup |
| Sensitive write | Spends money, sends something to someone else, or deletes data that can't be recovered. None of these tools is one: the connector never buys anything, automatic top-up is off for Muse lookups, Muse lookups send no webhooks, and cancelling a lookup deletes nothing (the same lookup can simply be started again). | None |
| Tool | Class | Scope | Usage |
|---|---|---|---|
start_people_search | Write | search | Uses included usage. Requires a paid plan for new searches. |
start_person_report | Write | dossier | Uses included usage unless the report is already cached in Muse mode. Requires a paid plan for new reports. |
start_person_question | Write | chat | Uses included usage. Questions declined before research starts use none. |
start_company_search | Write | search | Uses included usage. Requires a paid plan for new searches. |
start_company_report | Write | dossier | Uses included usage unless the report is already cached in Muse mode. Requires a paid plan for new reports. |
start_vehicle_report | Write | dossier | Uses included usage unless the report is already cached. Requires a paid plan for new reports. |
get_lookup | Read | history:read | None. |
list_lookups | Read | history:read | None. |
cancel_lookup | Write | The lookup's own scope | None. |
start_people_searchWriteFind the public profiles that match a name, phone number, email address or username.
- Inputs
query(required): The name, phone number, email address or username to look up (up to 240 characters).type(optional): How to read the query: name (default), phone, email or username.
- Returns
- Ranked candidates with confidence scores, city-level locations and sources; for a phone number, its carrier, line type and region.
- Side effects
- Uses included usage (never buys more). Creates a lookup record kept for 30 days. Nothing is purchased, sent or posted.
- Usage
- Uses included usage. Requires a paid plan for new searches.
- Scope
search- Typical time
- 95 s median, 158 s at the 90th percentile, measured in production.
start_person_reportWriteBuild a sourced public profile of one person.
- Inputs
name(required): The person's full name.headline(optional): A descriptor that tells namesakes apart, such as 'Engineer, London'.username(optional): A known public username outside Meta platforms.search_lookup_id(optional): The lookup_id of a search you ran from Muse. With candidate_id, pins the exact candidate.candidate_id(optional): The id of a candidate from that search's result. Requires search_lookup_id.
- Returns
- Identity, work, education, public accounts, city-level locations, mentions, a summary and numbered sources.
- Side effects
- Uses included usage (never buys more). Creates a lookup record kept for 30 days. Nothing is purchased, sent or posted.
- Usage
- Uses included usage unless the report is already cached in Muse mode. Requires a paid plan for new reports.
- Scope
dossier- Typical time
- 162 s median, 245 s at the 90th percentile, measured in production.
start_person_questionWriteAnswer one specific question about a person, with citations.
- Inputs
name(required): The person the question is about.question(required): The question, such as 'Where does she work now?'.report_lookup_id(optional): The lookup_id of a person report you ran from Muse, used to ground the answer.
- Returns
- A cited answer and suggested follow-up questions, or a short refusal for a question Muse mode declines.
- Side effects
- Uses included usage (never buys more). Creates a lookup record kept for 30 days. Nothing is purchased, sent or posted.
- Usage
- Uses included usage. Questions declined before research starts use none.
- Scope
chat- Typical time
- 13 s median, 26 s at the 90th percentile, measured in production.
start_company_searchWriteFind the legal entities that match a company name or domain.
- Inputs
query(required): The company name or domain (up to 240 characters).
- Returns
- Candidate companies with jurisdiction, registry identifiers, status and website.
- Side effects
- Uses included usage (never buys more). Creates a lookup record kept for 30 days. Nothing is purchased, sent or posted.
- Usage
- Uses included usage. Requires a paid plan for new searches.
- Scope
search- Typical time
- Not measured yet.
start_company_reportWriteBuild a sourced profile of one company.
- Inputs
name(required): The company's name.domain(optional): The company's website domain, such as northwind.example.jurisdiction(optional): Where the entity is registered, such as 'Delaware, US'.search_lookup_id(optional): The lookup_id of a search you ran from Muse. With candidate_id, pins the exact candidate.candidate_id(optional): The id of a candidate from that search's result. Requires search_lookup_id.
- Returns
- Registration, industry, executives, locations, linkage, contact channels, mentions, a summary and sources.
- Side effects
- Uses included usage (never buys more). Creates a lookup record kept for 30 days. Nothing is purchased, sent or posted.
- Usage
- Uses included usage unless the report is already cached in Muse mode. Requires a paid plan for new reports.
- Scope
dossier- Typical time
- Not measured yet.
start_vehicle_reportWriteDecode a VIN and report recalls, ratings and available history.
- Inputs
vin(required): The 17-character vehicle identification number.
- Returns
- Specifications, safety ratings, recalls, history records, a summary and sources.
- Side effects
- Uses included usage (never buys more). Creates a lookup record kept for 30 days. Nothing is purchased, sent or posted.
- Usage
- Uses included usage unless the report is already cached. Requires a paid plan for new reports.
- Scope
dossier- Typical time
- Not measured yet.
get_lookupReadCheck a lookup's status and read its result.
- Inputs
lookup_id(required): The lookup_id a start tool returned.
- Returns
- The lookup's status and, once it has succeeded, its result.
- Side effects
- None.
- Usage
- None.
- Scope
history:read
list_lookupsReadList recent lookups and their status.
- Inputs
limit(optional): How many to return, 1-20 (default 10).cursor(optional): The next_cursor from a previous page.
- Returns
- Up to 20 lookups from the last 30 days, newest first, and a cursor for more.
- Side effects
- None.
- Usage
- None.
- Scope
history:read
cancel_lookupWriteStop a lookup that is still running.
- Inputs
lookup_id(required): The lookup_id to cancel.
- Returns
- The lookup, now cancelled, or unchanged if it had already finished.
- Side effects
- Stops the lookup permanently. Usage for work already done may still count.
- Usage
- None.
- Scope
- The lookup's own scope
Lookup status
| Status | Meaning | Final | Next step |
|---|---|---|---|
queued | Accepted and waiting for a worker. | No | Call get_lookup with the lookup_id. |
running | Research is in progress. | No | Call get_lookup again; it waits up to 20 seconds each time. |
succeeded | Finished. The result is included. | Yes | Use the result. |
failed | Could not finish. The error explains why and what to do. | Yes | Relay the error; retry only if it says to. |
cancelled | Stopped by cancel_lookup. | Yes | Start a new lookup if still needed. |
- Every start tool waits up to 20 seconds. A lookup that finishes in that time comes back with its result; otherwise the reply is
queuedorrunningwith alookup_id. - Pass that
lookup_idtoget_lookup. It also waits up to 20 seconds per call, so call it again straight away instead of pausing between calls. - Repeating the same request within 15 minutes returns the existing lookup instead of starting, and charging for, another.
- Up to 3 lookups run at once per account; another start returns
too_many_active_lookups. - Finished lookups stay readable for 30 days, and
list_lookupsreturns them newest first.
Errors
Sign-in failures arrive as HTTP 401 or 403 with a WWW-Authenticate challenge. Tool errors carry a code, a message to relay and, when there is somewhere to send the user, a url.
| Code | HTTP | Tell the user | Then |
|---|---|---|---|
invalid_token | 401 | Deep Search needs to be reconnected. | Re-run OAuth from the challenge's resource metadata. |
insufficient_scope | 403 | This Deep Search connection is read-only, so it can't start lookups. | Ask the user to reconnect with full access. |
upgrade_required | 402 | New searches and reports need a Deep Search plan. | Relay the message and its link. |
usage_exhausted | 402 | This account's included Deep Search usage is used up. | Relay the message and its link; usage resets on the date given. |
invalid_arguments | - | The request was missing or had an invalid field. | Fix the named field and call again. |
unsupported_query_in_mode | - | Deep Search's Muse mode doesn't run this kind of lookup. | Explain the limit; don't retry the same request. |
question_declined | - | Deep Search doesn't answer this kind of question about a person. | Explain the limit; no usage was used. |
lookup_not_found | - | That lookup doesn't exist for this account. | Start a new lookup. |
candidate_not_found | - | That candidate isn't in the search you named. | Use an id from that search's result, or pass only the name. |
too_many_active_lookups | - | Three lookups are already running for this account. | Wait for one to finish with get_lookup, or cancel one. |
rate_limited | 429 | Too many requests in a short time. | Wait for the Retry-After period, then retry. |
temporarily_unavailable | 503 | Deep Search is briefly unable to start lookups. | Retry in a minute. |
Rate limits
| Applies to | Limit | Notes |
|---|---|---|
| Per connection | 120 requests a minute | Every call made with one access token. |
| Per IP address | 1,200 requests a minute | Wide on purpose: Muse users share Meta's server addresses. |
| Per account | 10 lookup starts a minute | Calls to the start_ tools. |
| Per account | 3 lookups running at once | Another start returns too_many_active_lookups until one finishes or is cancelled. |
A call over a limit returns rate_limited. Wait for its Retry-After period before retrying.
What Muse mode leaves out
Research run for a Muse user should not draw on Meta's own platforms, identify people by their faces, or reach into the private and sensitive parts of someone's life. Muse mode applies to every lookup this endpoint runs, and it can't be switched off.
| Left out | What that means |
|---|---|
| Meta platforms | Instagram, Facebook, Threads, WhatsApp and Messenger are never searched, fetched or cited. |
| Face matching and photos | Faces are never compared. Results carry no photos, except a public figure's Wikimedia portrait identified through Wikidata. |
| Sensitive characteristics | Health, sexual orientation, religion, political views and ethnicity are never inferred, and questions about them are declined. |
| Personal life | Dating-site presence, relationships, relatives and adult-site accounts are left out. |
| Breach and account data | Data-breach lists and the services an email address is registered with are left out. |
| Precise locations and contact details | Locations are city or region only. Contact details are limited to the identifier you supplied. |
| Profile scrapers | Paid social-profile scraping services aren't used. |
Data and retention
- A lookup's inputs and result are stored so
get_lookupcan return them, and deleted 30 days after the lookup finishes. - Each call records usage metadata: the account, the connection, the tool, its status and duration, and the usage charged. The query text is not part of it.
- Person and company reports built in Muse mode are cached apart from the main service's reports, reused for up to 30 days, then rebuilt. Vehicle reports, built the same way in both modes, share the standard vehicle cache.
- The privacy policy covers connected assistants and shared report caches in full.
Access and usage
- A Deep Search account. Each Muse user connects their own account by signing in on Deep Search's consent screen.
- New people, company and vehicle searches and reports need a Deep Search Pro subscription or a credit purchase. Without one, a start tool returns upgrade_required with a link to the plans page. Questions about a person use the account's included usage. A report already built in Muse mode comes back without using usage, and reading, listing or cancelling lookups never uses any.
- Nothing is bought through the connector. Lookups draw only on usage the account already has, and automatic top-up is off for Muse lookups.
- No regional restriction on Deep Search's side. Account holders must be 18 or older.
Acceptable use
Suitable uses include:
- Due diligence on a supplier, vendor or business contact before you sign or meet.
- Verifying a professional background someone has given you.
- Reconnecting with a former colleague.
- Researching a company before you work with it.
- Checking a used car's VIN for recalls and history before you buy.
Never use the connector for:
- Locating, monitoring or contacting someone against their wishes.
- Researching children.
- Employment, credit, housing, insurance or other eligibility decisions. Deep Search is not a consumer reporting agency.
- Identifying someone from a photo, or any facial recognition or biometric identification.
- Inferring anyone's health, sexual orientation, religion, political views or ethnicity.
- Harassing, threatening or exposing anyone.
The terms set out the complete policy. Anyone can ask us to suppress results about them through Remove my info.
Example prompts
What people ask Muse to do with Deep Search, and the tools it reaches for. Every name and identifier below is invented.
“We're about to sign a supply contract with Northwind Robotics. Find the right legal entity and build a sourced company report on it.”
Supplier due diligence. The report pins the entity the user picks from the search; get_lookup collects it if it outlasts the first wait.
“I'm meeting Dana Whitfield, head of procurement at Northwind Robotics, on Thursday. Build me a sourced profile of her professional background.”
Preparing for a business meeting: work history, education and public accounts, each claim linked to its source.
“Jordan Avery says he led engineering at Halden Labs until 2023. Do public sources back that up?”
Verifying a stated role: one cited answer, usually within the first wait, without building a whole report.
“Find Priya Raman, who worked with me at Halden Labs in Leeds around 2018. I'd like to get back in touch.”
Reconnecting with a former colleague: distinct people with that name, each with a confidence score and sources, so the user can pick the right one.
“A new supplier's account manager emailed me from sam.okafor@example.com. Which public profiles match that address?”
Checking a business contact: one email address resolved to ranked candidates with confidence scores and sources.
“I'm looking at a used car with VIN 1HGCM82633A004352. Does it have open recalls or title problems?”
Buying a used car: decoded specifications, safety ratings, open recalls and available history records.
“What happened to the lookups I started this morning? Cancel the company report if it's still running.”
Managing lookups: reads the account's recent Muse lookups and cancels only the one the user names.