MCP Tools Reference

All tools available through the ExoGraph MCP server.

Available Tools

1. search_entities

Search for entities in your knowledge graphs.

Usage in Claude:

"Search my ExoGraph for quantum computing"

Parameters:

query (string, required): Search query
n_results (integer, optional): Number of results (default: 10)
graph_id (string, optional): Limit to specific graph
graph_scope (string, optional): Search scope - "world" or "private" (defaults to header value)

Scope Options:

Use X-Graph-Scope: world header or graph_scope: "world" in arguments to search shared world graph
Use X-Graph-Scope: private header or graph_scope: "private" in arguments to search only your private graphs

Returns: Formatted list of entities with relevance scores and context snippets.

Example Output:

🔍 Search Results for 'quantum computing'

Found 3 entities:

1. **quantum error correction**
   Relevance: 0.92
   Context: Techniques to protect quantum information...

2. **quantum entanglement**
   Relevance: 0.85
   Context: A phenomenon where quantum states...

API Cost: Free (search operations)

2. get_world_graph

Explore relationships for an entity in the world knowledge graph.

Usage in Claude:

"How does 'neural networks' relate to 'deep learning' in ExoGraph?"

Parameters:

entity_id (string, required): Entity to explore
evidence (boolean, optional): Include source documents (default: false)

Returns: Entity relationships with connection strength and optional evidence.

Example Output:

🌐 World Graph: neural networks

Found 8 related entities:

→ **deep learning**
   Relationship: is_type_of
   Strength: 15 connections
   Sources: paper_123.pdf, doc_456.pdf

→ **backpropagation**
   Relationship: uses_technique
   Strength: 8 connections

API Cost: Free (graph operations)

3. list_graphs

List all your knowledge graphs.

Usage in Claude:

"Show me all my ExoGraph graphs"

Parameters:

graph_scope (string, optional): Filter by scope - "world" or "private" (defaults to header value)

Returns: List of graphs with metadata (ID, name, creation date, type, scope).

Scope Indicators:

🌐 World graphs (shared knowledge, earn tokens when others query)
🔒 Private graphs (your personal knowledge)

Example Output:

📊 Your Knowledge Graphs

Found 3 graph(s):

1. 🌐 **ML Research Papers**
   ID: `graph_abc123`
   Scope: world
   Created: 2025-10-15
   Type: document

2. 🔒 **Personal Notes**
   ID: `graph_def456`
   Scope: private
   Created: 2025-10-20
   Type: manual

3. 🌐 **World Graph**
   ID: `world`
   Scope: world
   Created: 2025-10-18
   Type: world

API Cost: Free

4. create_research_session

Start an AI-powered autonomous research session.

Usage in Claude:

"Start ExoGraph research on transformer architectures"

Parameters:

query (string, required): Research topic
budget_credits (number, optional): Credit limit
graph_id (string, optional): Target graph
graph_scope (string, optional): Research scope - "world" or "private" (defaults to header value)

Scope Options:

World scope: Research contributes to shared world graph, you earn tokens when others query results
Private scope: Research stays private, only accessible to you

Returns: Session ID and status information.

Example Output:

🔬 Research Session Created

Topic: transformer architectures
Session ID: `550e8400-e29b-41d4-a716-446655440000`
Status: pending

The research agent will begin investigating this topic.
Use get_research_status to check progress.

API Cost: Varies by model (30-100 credits)

Learn more about research →

5. get_research_status

Check the status of a research session.

Usage in Claude:

"Check the status of ExoGraph research session 550e8400-e29b-41d4-a716-446655440000"

Parameters:

session_id (string, required): Research session ID

Returns: Current status, progress, and summary if completed.

Example Output:

📋 Research Session Status

Topic: transformer architectures
Status: completed
Created: 2025-10-26 14:30
Completed: 2025-10-26 14:45

✅ Research Complete!

Found 15 academic papers and 8 technical articles
on transformer architectures. Key findings include...

API Cost: Free (status check)

6. upload_document

Upload a document (PDF or DOCX) to ExoGraph.

Usage in Claude:

"Upload the document at /path/to/paper.pdf to my ExoGraph"

Parameters:

file_path (string, optional): Local file path (server-accessible)
file_content_base64 (string, optional): Base64-encoded file content
filename (string, required if using file_content_base64): Filename with extension (.pdf or .docx)
graph_scope (string, optional): Document scope - "world" or "private" (defaults to header value)

Note: MCP clients typically use file_content_base64 for network transfers. The file must be base64-encoded and the filename must be provided.

Returns: Document metadata including document ID and graph ID.

Example Output:

✅ Document Uploaded Successfully

Filename: research_paper.pdf
Document ID: `00f1e557-7080-472c-9527-1ee6a9d35652`
Pages: 15
Scope: 🌐 world
Graph ID: `8528576f-dd6d-4572-8f99-2594d9117c15`

Document has been processed and indexed.

API Cost: 5 credits + 1 credit per page

7. list_documents

List all documents available to the user, filtered by graph scope.

Usage in Claude:

"Show me all my documents in ExoGraph"

Parameters:

graph_scope (string, optional): Filter by scope - "world" or "private" (defaults to header value)

Returns: List of documents with metadata (ID, title, pages, creation date, scope).

Example Output:

📄 Documents (🌐 world)

1. 🌐 **research_paper.pdf**
   Document ID: `00f1e557-7080-472c-9527-1ee6a9d35652`
   Pages: 15
   Created: 2025-11-06

2. 🔒 **personal_notes.pdf**
   Document ID: `abc123...`
   Pages: 5
   Created: 2025-11-05

API Cost: Free

8. list_research_sessions

List all research sessions for the user, filtered by graph scope.

Usage in Claude:

"Show me my ExoGraph research sessions"

Parameters:

graph_scope (string, optional): Filter by scope - "world" or "private" (defaults to header value)
limit (integer, optional): Maximum number of sessions (default: 10)

Returns: List of research sessions with status and metadata.

Example Output:

📊 Research Sessions (🌐 world)

1. ⏸️ **test research topic**
   Session ID: `9ad092af-8350-4d20-b2ee-0619da8ed118`
   Status: pending
   Created: 2025-11-06

2. ✅ **quantum computing**
   Session ID: `550e8400-e29b-41d4-a716-446655440000`
   Status: completed
   Created: 2025-11-05

API Cost: Free

9. create_chat_session

Create a new chat session for multi-turn conversations.

Usage in Claude:

"Create a new ExoGraph chat session about machine learning"

Parameters:

title (string, optional): Session title (auto-generated if not provided)
model_name (string, optional): Model to use - "snap" (fast) or "ponder" (deep thinking). Default: "snap"
reasoning_engine (string, optional): Reasoning engine - "rag", "graph", or "web". Default: "rag"
graph_scope (string, optional): Chat scope - "world" or "private" (defaults to header value)

Models:

snap: Fast responses for quick conversations
ponder: Deep thinking for complex analysis

Returns: Session ID and metadata.

Example Output:

💬 Chat Session Created

Title: Machine Learning Discussion
Session ID: `61124873-a318-47be-9ffe-3d6e220df3d1`
Scope: 🌐 world
Model: snap
Engine: graph

API Cost: Free (session creation)

10. list_chat_sessions

List all chat sessions for the user, filtered by graph scope.

Usage in Claude:

"Show me my ExoGraph chat sessions"

Parameters:

graph_scope (string, optional): Filter by scope - "world" or "private" (defaults to header value)

Returns: List of chat sessions with metadata.

Example Output:

💬 Chat Sessions (🌐 world)

1. **Machine Learning Discussion**
   Session ID: `61124873-a318-47be-9ffe-3d6e220df3d1`
   Model: snap
   Engine: graph
   Updated: 2025-11-06

API Cost: Free

11. send_chat_message

Send a message in a chat session. Creates a new session if session_id is not provided.

Usage in Claude:

"Send a message to ExoGraph: 'Tell me about IBM'"

Parameters:

message (string, required): The message content to send
session_id (string, optional): Existing session ID to continue conversation
model (string, optional): Model to use - "snap" (fast) or "ponder" (deep thinking). Default: "snap"
reasoning_engine (string, optional): Reasoning engine - "rag", "graph", or "web". Default: "graph"
graph_scope (string, optional): Chat scope - "world" or "private" (defaults to header value)
graph_id (string, optional): Target specific graph ID

Returns: Assistant response with usage information.

Example Output:

💬 Chat Response

IBM, originally founded as CTR, has a focus on artificial intelligence 
and has been involved in various projects such as the Social Security Act 
and the Early Space Program.

Usage: 3 tokens | Balance: 1005 credits

API Cost: Varies by model (3 credits for snap, 10 credits for ponder)

Using Tools

You don't need to memorize tool names or parameters. Just use natural language:

What You Say	Tool Used
"Search for X"	search_entities
"How does X relate to Y?"	get_world_graph
"List my graphs"	list_graphs
"Research X"	create_research_session
"Check status of..."	get_research_status
"Upload document X"	upload_document
"List my documents"	list_documents
"Show my research sessions"	list_research_sessions
"Create a chat session"	create_chat_session
"Show my chats"	list_chat_sessions
"Send message to ExoGraph"	send_chat_message

Claude automatically:

Picks the right tool
Fills in parameters
Formats the response nicely

Chaining Tools

Claude can use multiple tools in sequence:

Example:

"Search my ExoGraph for machine learning, then show me how the top result relates to other concepts, and if we need more information, start a research session"

Claude will:

Use search_entities to find results
Use get_world_graph on the top result
Decide if research is needed
Use create_research_session if appropriate

Rate Limits & Pricing

MCP tools use the same rate limits as the REST API:

Rate Limit: 60 requests/minute, 10,000/day
Costs: Same as REST API equivalents
Balance: Shared with web/API usage

View Pricing →

View Rate Limits →

Tool Comparison: MCP vs REST API

Feature	MCP	REST API
Ease of Use	Natural language	Code required
Setup Time	30 seconds	Variable
Authentication	Same API key	Same API key
Rate Limits	Same limits	Same limits
Pricing	Same costs	Same costs
Use Case	Interactive AI	Programmatic

When to use MCP:

Quick exploration
Interactive research
Ad-hoc queries
Learning the system

When to use REST API:

Production applications
Automated workflows
Custom integrations
High-volume operations

REST API Documentation →

Next Steps

Usage Examples - Real-world workflows
Troubleshooting - Common issues
REST API - Direct API access

MCP Tools Reference ​

Available Tools ​

1. search_entities ​

2. get_world_graph ​

3. list_graphs ​

4. create_research_session ​

5. get_research_status ​

6. upload_document ​

7. list_documents ​

8. list_research_sessions ​

9. create_chat_session ​

10. list_chat_sessions ​

11. send_chat_message ​

Using Tools ​

Chaining Tools ​

Rate Limits & Pricing ​

Tool Comparison: MCP vs REST API ​

Next Steps ​

MCP Tools Reference

Available Tools

1. search_entities

2. get_world_graph

3. list_graphs

4. create_research_session

5. get_research_status

6. upload_document

7. list_documents

8. list_research_sessions

9. create_chat_session

10. list_chat_sessions

11. send_chat_message

Using Tools

Chaining Tools

Rate Limits & Pricing

Tool Comparison: MCP vs REST API

Next Steps