orka
Request AccessSign In

MCP Integration

Connect to Orka from Claude Desktop, VS Code, and other MCP-compatible tools.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. With MCP, you can use Orka directly from tools like:

  • Claude Desktop
  • VS Code with Claude extension
  • Other MCP-compatible AI interfaces

This means you can query your documents and agents without leaving your workflow.

Getting Started

Prerequisites

  • An Orka account with at least one agent
  • An API key (generate one in the Keys section of your dashboard)
  • An MCP-compatible client (e.g., Claude Desktop)

Claude Desktop Configuration

Add Orka to your Claude Desktop configuration:

  1. Open Claude Desktop settings
  2. Navigate to the MCP servers configuration
  3. Add the following configuration:
json
1{
2  "mcpServers": {
3    "orka": {
4      "command": "npx",
5      "args": ["-y", "@orka/mcp-server"],
6      "env": {
7        "ORKA_API_KEY": "your-api-key",
8        "ORKA_API_URL": "https://api.orka.ai"
9      }
10    }
11  }
12}
  1. Replace your-api-key with your actual API key
  2. Restart Claude Desktop

VS Code Configuration

For VS Code with the Claude extension:

  1. Open VS Code settings
  2. Search for "Claude MCP"
  3. Add the Orka server configuration:
json
1{
2  "claude.mcpServers": {
3    "orka": {
4      "command": "npx",
5      "args": ["-y", "@orka/mcp-server"],
6      "env": {
7        "ORKA_API_KEY": "your-api-key",
8        "ORKA_API_URL": "https://api.orka.ai"
9      }
10    }
11  }
12}

Available Tools

Once connected, the following tools are available to your AI assistant:

query_agent

Send a query to an Orka agent and receive a response with citations.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agent_id | string | Yes | The agent to query | | query | string | Yes | Your question | | conversation_id | string | No | Continue an existing conversation |

Example usage in Claude:

"Using Orka, ask the Contract Analyst agent: which contracts have termination clauses?"

list_agents

List all available agents in your workspace.

Parameters: None

Example usage in Claude:

"Show me all my Orka agents"

search_documents

Perform semantic search across documents in a datastore.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | datastore_id | string | Yes | The datastore to search | | query | string | Yes | Search query | | limit | integer | No | Max results (default: 10) |

Example usage in Claude:

"Search my legal documents for mentions of liability caps"

list_datastores

List all datastores in your workspace with document counts.

Parameters: None

Example usage in Claude:

"What datastores do I have in Orka?"

Example Usage

Here are some example conversations using Orka through MCP:

Querying an Agent

You: "Ask my Contract Analyst to summarize the key risks in the Acme Corp agreement"

Claude: Uses the query_agent tool

"Based on the Contract Analyst's review, here are the key risks in the Acme Corp agreement:

  1. High liability cap - $2.1M liability exposure [1]
  2. Termination clause - Either party can terminate with 30 days notice [2]
  3. Payment terms - Net 90 payment terms increase cash flow risk

[1] Acme Corp Agreement, Page 8 [2] Acme Corp Agreement, Page 12"

Searching Documents

You: "Search my HR documents for information about parental leave policy"

Claude: Uses the search_documents tool

"I found 3 relevant documents about parental leave:

  1. Employee Handbook v3.pdf (p. 45) - Primary parental leave policy details
  2. Benefits Summary 2024.pdf (p. 12) - Leave duration and pay information
  3. HR FAQ.docx - Common questions about leave requests"

Multi-step Workflow

You: "List my agents and then ask the Customer Support agent about return policies"

Claude: Uses list_agents, then query_agent

"You have 3 agents:

  • Contract Analyst
  • Customer Support Agent
  • Research Assistant

Asking Customer Support Agent about return policies...

Our return policy allows returns within 30 days of purchase for a full refund. Items must be unused and in original packaging. [1]

[1] Return Policy.pdf, Page 1"

Troubleshooting

"Connection failed" error

  1. Verify your API key is correct
  2. Check that the API URL is https://api.orka.ai
  3. Ensure your API key has not expired
  4. Try regenerating your API key

"Agent not found" error

  1. Verify the agent ID is correct
  2. Check that the agent exists in your workspace
  3. Ensure your API key has access to the workspace

"No results" from search

  1. Verify the datastore ID is correct
  2. Check that documents have been processed (status: completed)
  3. Try a broader search query

MCP server not starting

  1. Ensure Node.js is installed (v18+)
  2. Check that npx is available in your PATH
  3. Try running npx -y @orka/mcp-server manually to see errors
  4. Verify environment variables are set correctly

Security Best Practices

  1. Use environment variables: Never hardcode API keys in configuration files that are committed to version control
  2. Rotate keys regularly: Generate new API keys periodically
  3. Use scoped keys: Create API keys with only the permissions needed
  4. Monitor usage: Check the Analytics section for unusual activity

Next Steps