MCP server

The Sourcely MCP server lets an AI assistant call this API as a tool. Ask ChatGPT or Claude to find sources for a paragraph, and it runs a search, waits for the result and cites what comes back.

MCP (Model Context Protocol) is the standard that assistants use to connect to tools. The MCP server is a client of this API: it sends the same requests you would, on behalf of your Sourcely account.

The hosted server's address is:

https://mcp.sourcely.net/mcp

It uses the Streamable HTTP transport. You don't install anything to use it.

Sign inCopy Anchor Link

The hosted MCP server is included with Sourcely Pro, Ultra and Max subscriptions; it does not use your prepaid credits. See Plan and limits. The server never uses a key of its own, so each assistant connects in one of two ways:

When an assistant connects with sign-in, a key named MCP connector (OAuth) appears in your dashboard's API keys list, with its own requests. Revoke that key to disconnect the assistant at once. Connecting again later creates a new one.

The server passes your credentials on to the API and never stores them. A request without credentials gets a tool error, and no search runs.

ChatGPTCopy Anchor Link

1. In ChatGPT on the web, open Plugins.
2. Select the + button, then Add custom MCP server.
3. Fill in the form:
   • Name: Sourcely
   • Description (optional): Find academic sources for a text
   • Connection: https://mcp.sourcely.net/mcp
   • Authentication: OAuth
4. Review the risk warning, select I understand and want to continue, then select Create as a plugin.
5. ChatGPT opens the Sourcely sign-in page. Sign in and approve access. ChatGPT then lists the server's 5 tools.
6. Install the plugin. In a new chat, type @, choose Sourcely and ask it to find sources for your text.

ChatGPT may ask you to confirm before it runs a tool that creates or deletes a search. Because sign-in includes offline access, ChatGPT renews its access on its own; you don't sign in again every day.

According to OpenAI, custom MCP servers are available on ChatGPT Business and Enterprise/Edu, on the web only. On a Business workspace, only admins and owners can add them. On Enterprise/Edu, admins can allow other members. If you don't see Plugins, your account may still use the older flow: Settings → Apps → Create, then enter the same URL, choose OAuth and select Scan Tools.

ClaudeCopy Anchor Link

Claude on the web, in the desktop app and on mobile uses the same connectors.

1. In Claude, open Settings → Connectors and select Add custom connector.
2. Enter https://mcp.sourcely.net/mcp as the URL, exactly as written, with no trailing slash.
3. If Claude asks how to register its OAuth client, choose Register automatically.
4. Add the connector, then select Connect. Claude opens the Sourcely sign-in page. Sign in and approve access.
5. In a chat, turn on Sourcely in the tools menu and ask Claude to find sources for your text.

Custom connectors work on Claude Free (one connector), Pro and Max. On Team and Enterprise, an owner adds the connector once, and each member then connects with their own Sourcely account.

Claude CodeCopy Anchor Link

Add the server, then sign in:

claude mcp add --transport http sourcely https://mcp.sourcely.net/mcp

Run /mcp inside Claude Code, select sourcely, then Authenticate. Your browser opens the Sourcely sign-in page.

To use an API key instead, pass it as a header:

claude mcp add --transport http sourcely https://mcp.sourcely.net/mcp --header "Authorization: Bearer srcly_your_key"

CursorCopy Anchor Link

Cursor connects to the hosted server directly and sends your key as a header.

1. Open ~/.cursor/mcp.json, or create it. A server added there is available in every project. To add it to one project only, use .cursor/mcp.json in that project instead, and keep the key out of version control.

2. Add the server:

   Copy Text

   {
     "mcpServers": {
       "sourcely": {
         "url": "https://mcp.sourcely.net/mcp",
         "headers": {
           "Authorization": "Bearer ${env:SOURCELY_API_KEY}"
         }
       }
     }
   }

   ${env:SOURCELY_API_KEY} reads the key from the environment. Cursor must be able to see that variable: on macOS, an app opened from the Dock doesn't get the variables set in your shell profile, so start Cursor from a terminal where SOURCELY_API_KEY is set. You can also write the key in place, as "Bearer srcly_your_key".

3. Restart Cursor, then open Cursor Settings → Tools & MCP. sourcely should be listed with a green status dot and its 5 tools.

4. In the agent chat, ask it to find sources. Cursor asks before running each tool, unless you allow it to run them automatically.

A red dot or a 401 error usually means the header is wrong or empty. Check that it starts with Bearer (with a space) and that the variable is set.

Other clientsCopy Anchor Link

Any MCP client that connects over Streamable HTTP works, such as VS Code, Windsurf or your own agent. Use https://mcp.sourcely.net/mcp as the URL, and either send the Authorization header with an API key or let the client sign in with OAuth if it supports it.

ToolsCopy Anchor Link

find_sources takes the create search options as arguments: text, mode, enrichment, granularity, max_claims and citation_formats. The filters are separate arguments too: year_from, year_to, min_citations, open_access, paper_types, venue, include_keywords and exclude_keywords. The meanings and defaults are the same as in create search.

ResultsCopy Anchor Link

Each tool returns the search as JSON with job_id, status, usage and a next_steps hint for the assistant. Unlike get search, tracks list their sources inline, in rank order, instead of by source ID:

{
  "job_id": "src_example",
  "status": "completed",
  "document": {
    "status": "done",
    "page": 1,
    "has_more": true,
    "sources": [
      {
        "rank": 1,
        "source_id": "s_1",
        "title": "Urban green space and mental health",
        "authors": ["Ada Lovelace"],
        "year": 2021,
        "url": "https://example.com/paper",
        "citation_count": 42,
        "score": 0.91,
        "citations": { "apa7": "Lovelace, A. (2021). Urban green space and mental health." },
        "enrichment": { "relevance": "Relevant", "analysis": "…", "paper_type": ["peer_reviewed"] }
      }
    ]
  },
  "usage": { "currency": "USD", "estimated_cost": 0.165, "actual_cost": 0.069, "discount_percent": 0 },
  "next_steps": "Search finished. Optional: load_more_sources fetches the next page of document sources."
}

Empty fields are left out. paper_type lists only the flags that are true. Scraped full text, from enrichment: "high", appears as full_text_available: true. Call get_search_results with include_full_text: true to get it, up to 20,000 characters per source.

WaitingCopy Anchor Link

find_sources, load_more_sources, refine_claim_sources and get_search_results check the search every 3 seconds. They return when it is completed or failed, or when wait_seconds runs out. The default is 45 seconds, because some clients stop a tool call after about a minute. If the search is still running, the result has its job_id and current status, and the assistant calls get_search_results again. See search states.

ErrorsCopy Anchor Link

API errors come back as tool errors that name the HTTP status and error code, so the assistant can explain them. See errors.

Invalid arguments, such as max_claims: 99, are rejected before any request reaches the API.

Plan and limitsCopy Anchor Link

The hosted server at mcp.sourcely.net is included with Sourcely Pro, Ultra and Max. Searches through it are not charged to your prepaid credits, and their usage shows a cost of 0.

The deep search allowance resets every 30 days, on the same date as in the app. When it runs out, deep searches through the MCP fail with deep_search_limit_reached until the reset, and quick searches keep working. Without a paid plan, every tool that starts a search fails with subscription_required.

Calling the API directly, or running the MCP server yourself, still uses prepaid credits as described in Credits and pricing.

The server tells the assistant to prefer quick searches and one well-scoped search over many small ones.

Run it yourselfCopy Anchor Link

You can also run the server on your own machine, for example against a local API. It lives in the repository's mcp_server/ folder and needs Python 3.10 or newer:

cd mcp_server
python3 -m venv .venv
.venv/bin/pip install -e .

Run locally, it uses the stdio transport: your client starts the server and the key comes from SOURCELY_API_KEY. For Claude Code:

claude mcp add sourcely --env SOURCELY_API_URL=http://localhost:8000 --env SOURCELY_API_KEY=srcly_your_key -- /absolute/path/to/mcp_server/.venv/bin/sourcely-mcp

sourcely-mcp --transport http serves the same tools over HTTP at /mcp, the way mcp.sourcely.net does. Over HTTP the server ignores its own SOURCELY_API_KEY by default, so a shared server never spends one account's balance on another user's request. The repository's mcp_server/README.md covers deploying it, and mcp_server/OAUTH.md covers turning on sign-in with MCP_OAUTH_ENABLED.