MCP Integration of Polyvia

Polyvia implements the Model Context Protocol (MCP), enabling seamless integration with AI assistants like Claude Desktop, IDEs, and other MCP-compatible tools.

Using Claude Code or Cursor? The Polyvia plugin installs the MCP server and agent skills in one command — no config editing required.

/plugin add polyvia-ai/skills

What is MCP?

Model Context Protocol is an open standard that allows AI applications to securely access external data sources and tools. Polyvia’s MCP server exposes your document workspace as a set of tools that AI assistants can use to ingest, browse, and query your documents — all without leaving the conversation. Polyvia’s MCP server is hosted at https://app.polyvia.ai/mcp and uses the streamable HTTP transport. No installation required — just point your client at the URL and pass your API key as a bearer token.

Connecting from Claude Code

Add the server with a single command:

claude mcp add --transport http polyvia https://app.polyvia.ai/mcp \
  --header "Authorization: Bearer poly_<your-key>"

This registers polyvia for the current project. Add --scope user to make it available in every project, or --scope project to share it with your team via a checked-in .mcp.json. Run claude mcp list to confirm it’s connected, then ask Claude about your documents.

Generate a dedicated API key for each MCP client so you can revoke it independently.

Connecting from Claude Desktop & other clients

Claude Desktop and most other MCP clients read a JSON config file rather than a CLI. Open (or create) ~/.claude/claude_desktop_config.json and add the polyvia entry:

{
  "mcpServers": {
    "polyvia": {
      "type": "http",
      "url": "https://app.polyvia.ai/mcp",
      "headers": {
        "Authorization": "Bearer poly_<your-key>"
      }
    }
  }
}

Restart Claude Desktop. You should see Polyvia appear in the MCP server list.

Connecting via SDK

Both the Python and TypeScript SDKs expose a client.mcp helper that generates the correct config for each major AI client.

Python method	TypeScript method	Use with
`claude_code_command()`	`claudeCodeCommand()`	The `claude mcp add …` command line
`to_anthropic_mcp_server()`	`toAnthropicMcpServer()`	Anthropic beta messages API
`to_openai_responses_tool()`	`toOpenAIResponsesTool()`	OpenAI Responses API
`to_openai_mcp_server()`	`toOpenAIMcpServer()`	OpenAI Agents SDK
`to_claude_desktop_config()`	`toClaudeDesktopConfig()`	Claude Desktop config file

Anthropic SDK

from anthropic import Anthropic
from polyvia import Polyvia

polyvia = Polyvia(api_key="poly_<key>")
ant     = Anthropic()

response = ant.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What are my Q4 findings?"}],
    mcp_servers=[polyvia.mcp.to_anthropic_mcp_server()],
    betas=["mcp-client-2025-04-04"],
)
print(response.content[0].text)

OpenAI Responses API

from openai import OpenAI
from polyvia import Polyvia

polyvia = Polyvia(api_key="poly_<key>")
oai     = OpenAI()

response = oai.responses.create(
    model="gpt-4o",
    tools=[polyvia.mcp.to_openai_responses_tool()],
    input="What are my Q4 findings?",
)
print(response.output_text)

OpenAI Agents SDK

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHTTP
from polyvia import Polyvia

polyvia = Polyvia(api_key="poly_<key>")
cfg = polyvia.mcp.to_openai_mcp_server()

server = MCPServerStreamableHTTP(url=cfg["url"], headers=cfg["headers"])
agent  = Agent(name="Research", mcp_servers=[server])
result = Runner.run_sync(agent, "What do my Q4 reports say about revenue?")
print(result.final_output)

Claude Desktop

# Print a snippet to copy-paste into ~/.claude/claude_desktop_config.json
client.mcp.print_claude_desktop_snippet()

# Or wire it up programmatically
import json, pathlib

cfg_path = pathlib.Path.home() / ".claude" / "claude_desktop_config.json"
config = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
config.setdefault("mcpServers", {})["polyvia"] = client.mcp.to_claude_desktop_config()
cfg_path.write_text(json.dumps(config, indent=2))

Agent Tools (programmatic)

For frameworks that don’t support remote MCP, use client.tools to get JSON-schema tool definitions and an executor that calls the REST API directly. All 10 Polyvia tools are available: ingest, status, list/get/update/delete documents, list/create/delete groups, and query.

Anthropic Messages API

import anthropic
from polyvia import Polyvia

client = Polyvia(api_key="poly_<key>")
ant    = anthropic.Anthropic()
tools, call = client.tools.anthropic()

response = ant.messages.create(
    model="claude-opus-4-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Summarise my Finance documents."}],
    tools=tools,
)
for block in response.content:
    if block.type == "tool_use":
        print(call(block.name, block.input))

OpenAI ChatCompletion

import json
from openai import OpenAI
from polyvia import Polyvia

client = Polyvia(api_key="poly_<key>")
oai    = OpenAI()
tools, call = client.tools.openai()

response = oai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What are my Q4 findings?"}],
    tools=tools,
)
for tc in response.choices[0].message.tool_calls or []:
    print(call(tc.function.name, json.loads(tc.function.arguments)))

LangChain (Python)

Requires pip install "polyvia[langchain]".

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from polyvia import Polyvia

client = Polyvia(api_key="poly_<key>")
tools  = client.tools.langchain()

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant with access to a document workspace."),
    ("user", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent    = create_tool_calling_agent(ChatOpenAI(model="gpt-4o"), tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
executor.invoke({"input": "What risks are mentioned in my reports?"})

Available Tools

`polyvia_ingest_document`

Upload a document from a public URL or raw base64 content. Parameters:

source_url (string, either/or): Publicly accessible URL of the document
file_content_base64 (string, either/or): Base64-encoded file bytes
file_name (string, required with base64): Filename with extension (e.g. report.pdf)
file_mime_type (string, optional): MIME type; inferred from file_name if omitted
name (string, optional): Display name in Polyvia

Returns { "document_id", "task_id", "status": "pending" }.

`polyvia_check_ingestion_status`

Poll a parse task started by polyvia_ingest_document. Parameters:

task_id (string, required): From polyvia_ingest_document

Returns { "task_id", "document_id", "status", "error" }.

`polyvia_list_documents`

List documents in your workspace. Parameters:

status (string, optional): Filter by uploading, parsing, completed, or failed
response_format (string, optional): markdown (default) or json

`polyvia_get_document`

Get metadata and summary for one document. Parameters:

document_id (string, required): From polyvia_list_documents
response_format (string, optional): markdown (default) or json

`polyvia_query`

Ask a natural-language question about your documents. Parameters:

query (string, required): Your question (max 2000 chars)
document_id (string, optional): Scope to one document
group_id (string, optional): Scope to documents in a specific group
group_ids (string[], optional): Scope to documents across multiple groups
Omit all three to search your entire workspace

Documents must have status=completed before they can be queried.

`polyvia_list_groups`

List all groups in your workspace. No parameters required. Returns an array of group objects with id, name, color, and created_at.

`polyvia_create_group`

Create a new group. Parameters:

name (string, required): Display name for the group

Returns { "group_id": "g_<id>" }.

`polyvia_update_document`

Move a document to a different group, or remove it from its current group. Parameters:

document_id (string, required): The document to update
group_id (string | null, required): Target group ID, or null to remove from any group

`polyvia_delete_document`

Permanently delete a document and all its indexed content. Parameters:

document_id (string, required): The document to delete

`polyvia_delete_group`

Delete a group. The group must be empty, or you must pass delete_documents: true to wipe its documents first. Parameters:

group_id (string, required): The group to delete
delete_documents (boolean, optional): If true, delete all documents in the group before deleting the group itself. Defaults to false.

Example Workflows

Ingest a public PDF and ask a question

User: Ingest this paper and tell me the main contributions:
      https://arxiv.org/pdf/2501.12345

Claude:
  1. polyvia_ingest_document(source_url="https://arxiv.org/pdf/2501.12345")
     → { document_id: "k57abc...", task_id: "3f2e..." }

  2. polyvia_check_ingestion_status(task_id="3f2e...")
     → status: "parsing" … (waits) … status: "completed"

  3. polyvia_query(query="What are the main contributions?",
                   document_id="k57abc...")
     → "The paper introduces three key contributions: ..."

Find information across your whole workspace

User: What do all my uploaded reports say about supply chain risks?

Claude:
  1. polyvia_list_documents(status="completed")
     → lists completed documents

  2. polyvia_query(query="What supply chain risks are mentioned across all reports?")
     → "Across your documents, three recurring supply chain risks appear: ..."

Check what documents you have before querying

User: Do I have anything about GDPR compliance?

Claude:
  1. polyvia_list_documents(status="completed", response_format="json")
     → scans titles and summaries

  2. polyvia_get_document(document_id="<matched-id>")
     → confirms the document is about GDPR

  3. polyvia_query(query="What does this document say about data retention?",
                   document_id="<matched-id>")
     → focused answer from that document

Troubleshooting

MCP server not appearing in Claude

Verify the configuration file path is correct (~/.claude/claude_desktop_config.json)
Check that the API key is valid and starts with poly_
Restart Claude Desktop completely
Check Claude’s logs for error messages

Authentication errors

Ensure your API key is correctly set in the Authorization header
Verify the API key has not been revoked or expired
Check that you have an active Polyvia account

Slow response times

Large workspaces may take longer to search
Use document_id in polyvia_query to narrow to a specific document

Next Steps

Python SDK

Full Python SDK reference

TypeScript SDK

Full TypeScript / JavaScript SDK reference

Polyvia API

Build custom integrations with the REST API

Polyvia Platform

Upload documents and manage your workspace

​What is MCP?

​Connecting from Claude Code

​Connecting from Claude Desktop & other clients

​Connecting via SDK

​Anthropic SDK

​OpenAI Responses API

​OpenAI Agents SDK

​Claude Desktop

​Agent Tools (programmatic)

​Anthropic Messages API

​OpenAI ChatCompletion

​LangChain (Python)

​Available Tools

​polyvia_ingest_document

​polyvia_check_ingestion_status

​polyvia_list_documents

​polyvia_get_document

​polyvia_query

​polyvia_list_groups

​polyvia_create_group

​polyvia_update_document

​polyvia_delete_document

​polyvia_delete_group

​Example Workflows

​Ingest a public PDF and ask a question

​Find information across your whole workspace

​Check what documents you have before querying

​Troubleshooting

​Next Steps

Python SDK

TypeScript SDK

Polyvia API

Polyvia Platform

What is MCP?

Connecting from Claude Code

Connecting from Claude Desktop & other clients

Connecting via SDK

Anthropic SDK

OpenAI Responses API

OpenAI Agents SDK

Claude Desktop

Agent Tools (programmatic)

Anthropic Messages API

OpenAI ChatCompletion

LangChain (Python)

Available Tools

`polyvia_ingest_document`

`polyvia_check_ingestion_status`

`polyvia_list_documents`

`polyvia_get_document`

`polyvia_query`

`polyvia_list_groups`

`polyvia_create_group`

`polyvia_update_document`

`polyvia_delete_document`

`polyvia_delete_group`

Example Workflows

Ingest a public PDF and ask a question

Find information across your whole workspace

Check what documents you have before querying

Troubleshooting

Next Steps