> For the complete user guide index, see [llms.txt](https://portraitresearch.com/documentation/llms.txt).

# Portrait MCP

[Canonical page](https://portraitresearch.com/documentation/integrations/portrait-mcp/)

## Applicability

- **Task:** Connect and verify Portrait MCP without assuming Easel or full web-app parity
- **Access:** Portrait account; OAuth; no self-service API key
- **Audience:** Portrait users and technical teams connecting an AI client
- **Surfaces:** mcp
- **Availability:** Available to Portrait accounts
- **Content type:** how-to
- **Last reviewed:** 2026-09-22

Portrait MCP connects a compatible AI client to a defined set of Portrait data and workflow tools. It uses your Portrait identity and entitlements; it does not grant additional data access.

## Before you connect

You need:

- a Portrait account;
- an MCP client that supports remote HTTP servers and OAuth;
- permission to use Portrait in that client; on a managed workspace, an authorized owner may need to add the connector first.

Portrait MCP uses remote HTTP and OAuth with automatic client registration. There is no Portrait API key or token to create, copy, or paste. Leave optional OAuth Client ID and Client Secret fields blank.

## Get the server URL

Open **Portrait MCP** from the user menu in the web app. Copy the server URL shown on that page.


## Connect a client

**Claude Desktop and Claude on the web**

> [!IMPORTANT]
> If **Add custom connector** is missing, check your Claude workspace and role first. Approval to install Claude Desktop does not itself grant permission to add an organization connector.

Use [Claude's connector page](https://claude.ai/customize/connectors) in your browser if you cannot find the controls in Desktop. Sign in to the same Claude account and workspace.

**Team or Enterprise**

1. Ask an **Owner or Primary Owner** to open **Organization settings → Connectors**.
2. The owner selects **Add → Custom → Web**, names it **Portrait Research**, enters the Portrait server URL, and adds it.
3. Each member opens **Customize → Connectors**, finds Portrait, and selects **Connect** to authorize their own Portrait account.

**Individual accounts**

1. Open **Customize → Connectors**.
2. Select **+ → Add custom connector**, name it **Portrait Research**, and enter the Portrait server URL.
3. Add the connector and complete Portrait authorization. Free accounts are limited to one custom connector.

Enable Portrait through **+ → Connectors** in the conversation, then follow [Verify the connection](#verify-the-connection).

These remote connectors work through your Claude account; they are separate from local Desktop extensions. See [Anthropic's current connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for current labels and plan requirements.

**Other clients**

- **Claude Code** — run `claude mcp add --transport http portrait-research <your-server-url>`. Then open Claude Code, run `/mcp`, select `portrait-research`, and complete OAuth in your browser.
- **ChatGPT** — where your plan and workspace permissions allow custom apps, create the app with the Portrait server URL, select OAuth, scan its tools, and complete authorization. Select Portrait from the tools menu for each message that needs to call it.

Client labels and menus can change. Follow the current [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) or [ChatGPT MCP apps documentation](https://help.openai.com/en/articles/12584461) when its UI differs from this guide.

## Verify the connection

1. Ask the client to identify the connected Portrait tools and call `about_portrait_mcp` if its host has not already supplied the server's orientation. Read its current instructions and `document_types` vocabulary.
2. Run a read-only request, such as `search_companies` or `entity_list` with `kind="project"`.
3. Open a returned Portrait link when available and compare the result with the web app signed in to the intended organization.

## Choose a tool and preserve its identifiers

Use the tools and argument schema advertised by your connected server. These are the main discovery routes:

| Intent | Route |
|---|---|
| Resolve a company | `search_companies`; copy the returned composite ticker rather than guessing its suffix |
| Inspect company intelligence | `get_company` with that ticker for an index, then request the required `sections` |
| Find or read source material | `search_documents`, then `read_document` with a returned document ID |
| Find saved work | `entity_list` for projects, chats, monitors, screens, or prompts, then the matching reader advertised by the server |
| Resolve research citations | For `[idx=N]`, use the matching `primer_citations` or `case_study_citations` section of `get_company`, or `get_research` with `part="citations"` for the exact chat and message |

Preserve returned IDs, company tickers and opaque cursors unchanged. Keep the same filters when paging; a single response may not contain all results. Do not infer missing source text from a summary or use a citation index from a different report.

## Source text and synthesized results

SEC filings can be returned as verbatim search snippets or paged document text. Licensed sources such as earnings transcripts are returned as synthesized analysis: `search_documents` uses its `summary` field, and `read_document` marks a whole-document summary with `is_summary=true`. Preserve that distinction in your answer. A generated summary is not a verbatim quotation from the source.

`search_documents` excludes news as a category. Third Bridge and FactSet documents are not directly exposed. A missing or inaccessible document can appear as `not_found`; that result is not proof that the document never existed. Source rights and coverage still apply to accessible material.

Search relevance scores are unnormalized, can be negative, and rank hits only within the same call. They are not confidence scores or evidence of exhaustive coverage. Read any truncation or size-budget hints, and narrow the query, companies, document types, date range, or result limit when needed. For the document-type filter, use the vocabulary returned by `about_portrait_mcp` or a supported type returned by the server.

## Capability boundaries

Depending on your account, client and organization permissions, and the tools exposed by the current server version, an MCP client can retrieve supported company intelligence, Portrait corpus documents, research, projects, screens, monitors, prompts, and usage information.

The following boundaries are material:

- MCP does not expose Easel;
- it does not expose Third Bridge or FactSet documents directly;
- it has no tools to browse or read My Library directly; the Deep Research context rules below still apply;
- source and metric depth remain limited by the connected user's firm entitlements.

## Start Deep Research

### Check prerequisites

The account must be eligible for usage-based Deep Research. The connected client must support action tools, expose the launch tool, and have the relevant permission. A connected MCP account alone does not establish those requirements.

### Review included context

- A launch can attach known My Library document IDs, including IDs supplied by an applicable saved prompt. MCP cannot browse My Library to find or read those files directly.
- Deep Research automatically looks for the latest version of My Library notes and uploads associated with any selected company. It uses that version only when its extracted text is ready for research. Unavailable content can be omitted; Portrait does not use an earlier version instead.
- When a Project is selected, its **Research instructions** apply automatically.

Review the company associations and the selected Project's Research instructions in the web app before approval. See [Select companies and sources](https://portraitresearch.com/documentation/research/select-companies-and-sources/) for all context and document-volume limits.

### Approve scope and cost

Starting Deep Research uses research credits and is **not idempotent**: submitting the same request again can start another metered run. A completion email is requested by default.

Before the client calls the launch tool, review:

1. The resolved question, companies, and date range.
2. The selected Project and its Research instructions.
3. Sources, attached documents, company-associated My Library context, and the web setting.
4. The notification setting and usage consequences.

Give the client explicit approval for that reviewed request before it starts the run.

## Troubleshooting

| Symptom | Check | Next action |
|---|---|---|
| **Add custom connector** is missing | Claude workspace, role, and connector settings | Use the Claude setup steps above; an organization owner may need to add Portrait before you can connect |
| Portrait is configured but Claude does not use it | Connection authorization and conversation tool selection | Connect your own Portrait account, enable Portrait in the conversation, and run the read-only verification in this guide |
| OAuth opens the wrong Portrait account | Active browser session and organization | Sign out of the unintended account and reconnect |
| A tool or source is missing | Server version, account access, and licensing boundary | Use a supported tool or contact the team with the client name and missing capability |
| The entire tool list is empty after a previous successful connection | A retained OAuth authorization may use an older scope set | Disconnect and reconnect the Portrait connector to authorize the current scopes; if still empty, report the client and server version to support |
| The client asks for an API key | Connector transport and authentication type | Configure remote HTTP with OAuth; do not invent or paste a token |
| A request needs Easel | MCP boundary | Use Easel in Portrait or a supported Easel bridge instead |

For unresolved connection problems, [contact the team](https://portraitresearch.com/documentation/more/contact-us/) with the client and version, Claude plan and workspace role, the step that failed, and the displayed error. Do not send passwords, tokens, or OAuth callback URLs. A missing client control and a failed Portrait authorization are different problems; report which one you encountered.

## Connecting a provider inside Easel

This page describes **external AI client → Portrait MCP**. **Easel → MCP provider** is a separate account-gated connection in Settings. That workflow requires a new or restarted session after connection, and BIA currently allows setup but not tool use. Read [Connect MCP providers inside Easel](https://portraitresearch.com/documentation/integrations/mcp-in-easel/) before diagnosing that direction.