Cognitia AI
Documentation
Everything you need to know about using Cognitia AI, connecting your tools, and getting the most out of your AI assistant.
Product Overview
Getting Started
Start HereCreate Your Account
Visit the login page and create your account using one of three methods:
Google Sign-In -- One-click sign up with your Google account. Fastest way to get started.
iCloud Sign-In -- Sign up with your Apple ID for seamless iCloud integration.
Email & Password -- Create an account with any email address and a secure password.
All new accounts start with a free tier. No credit card required.
Connect Your First Integration
After signing in, navigate to the sidebar and connect your first service. We recommend starting with Gmail as it unlocks both email and calendar capabilities:
Click the Email integration button in the sidebar
Select Gmail and authorize Cognitia to access your account
Once connected, you can ask Cognitia to read, search, and send emails, plus manage your Google Calendar
Send Your First Message
Navigate to the Chat page and start a conversation. Cognitia adapts to natural language -- just tell it what you need:
"Summarize my unread emails from today"
"What meetings do I have this week?"
"Search the web for the latest AI news"
"Help me draft an email to my team"
Integrations Guide
MCP Marketplace
What is the MCP Marketplace?
The MCP Marketplace allows you to browse and connect external MCP (Model Context Protocol) servers to extend Cognitia with additional tools and capabilities. MCP is an open standard that lets AI assistants interact with external services through a unified protocol. By connecting external MCP servers, you can add tools for services like Notion, Slack, databases, and many more — all without any coding.
Key highlights:
Available to all subscription tiers
No additional cost beyond LLM credits
Connect unlimited external servers
Built-in tools always take priority
Connecting an MCP Server
There are two ways to add external MCP servers:
Option 1: Browse the Official MCP Registry
Open the MCP Marketplace from the sidebar
Use the search bar or quick-search tags to find a server (e.g., "Notion", "Slack")
Click Connect next to the server you want to add
Enter any required authentication credentials (API key, bearer token, etc.)
Cognitia will test the connection and cache the available tools
Option 2: Add a Custom Server
Click Add Custom Server in the MCP Marketplace
Enter a server name, its URL, and authentication details
Click Connect & Test to verify and save
Managing Connected Servers
Once connected, each server appears as a card in the MCP Marketplace page showing its status, tool count, and last connection time. You can:
Toggle active/inactive: Temporarily disable a server without removing it. Inactive servers' tools are excluded from conversations.
Refresh tools: Re-fetch the tool list from the server if it has been updated.
Remove a server: Permanently disconnect and delete the server from your account.
Expand tool list: View all individual tools provided by the server.
Pricing and Tool Overlap
There is no additional credit cost for using external MCP tools. The only cost is the normal LLM token usage that applies to every message — tool definitions and results are part of the token count, just like built-in tools.
If an external server provides tools that overlap with a built-in Cognitia integration (e.g., a Gmail MCP server when you already have Gmail connected natively), the built-in integration takes priority automatically. This ensures you always get the best experience with native integrations while still being able to extend with external tools for services Cognitia doesn't cover natively.
MCP Memory Layer
NewWhat is the MCP Memory Layer?
The MCP Memory Layer lets you use the personal memory you've built with Cognitia from any external MCP-compatible client — including Cursor, Claude Desktop, Claude Code, Windsurf, and more. Your knowledge graph, conversation history, emails, files, financial data, social media, and multimodal identity data are all accessible through a single unified endpoint.
Instead of your memory being locked inside Cognitia, external AI agents can query it as context. For example, a coding agent in Cursor could retrieve your project-related knowledge, or Claude Desktop could recall your preferences and recent conversations.
Memory layers available:
Knowledge Graph
Entities & relationships
Temporal facts & timeline
Behavioral profile
Store new knowledge
Data Sources
Email search
Financial data
Social media
Cloud files
Multimodal (Premium)
Face recognition
Voice identification
Visual object matching
Quick Start
Connecting takes one step — add the Cognitia MCP endpoint URL to your client. OAuth handles everything else automatically.
Cursor / Claude Desktop / Claude Code
Add this to your MCP client configuration file:
{ "mcpServers": { "cognitia-memory": { "url": "https://cognitia.co/api/mcp" } } }
Add the configuration above to your MCP client settings.
On first connection, your client opens a browser window. Log into Cognitia if prompted.
On the consent screen, select which memory sub-tools to grant access to, then click Allow Access.
Done. The external client now has access to the tools you selected. Token refresh is automatic.
Authentication
Cognitia's MCP server supports OAuth 2.1 with PKCE, the same industry-standard protocol used by Notion, Linear, and other MCP services. Clients that support OAuth (Cursor, Claude Desktop, Claude Code) handle the entire flow automatically.
OAuth 2.1 (automatic)
No tokens or API keys to manage. The client handles login, consent, token exchange, and automatic refresh. You just add the URL and approve the connection once.
Bearer Token (manual)
For clients that don't support OAuth, you can pass a Bearer Token in the Authorization header. Tokens expire after 1 hour and require manual renewal. Set the header to Authorization: Bearer YOUR_TOKEN.
To get your token, go to Data Platform → API & Monetization and click Generate Bearer Token. Copy the token and use it in your client's Authorization header. Generate a new one when it expires.
Available Tools
Two MCP tools are exposed to external clients:
The main query tool. Send a natural-language query and the agent autonomously decides which sub-tools to call — knowledge graph search, email search, file search, financial data, or multimodal identity matching. It runs an internal LLM agent loop and returns a synthesized context summary along with structured entities, facts, and signals.
Example queries: "What do I know about Project Atlas?", "Find my recent emails about the budget meeting", "What are my current goals?", "Remember that I prefer dark mode in all apps."
A configuration tool to list and toggle which sub-tools are available to the memory agent. Use action: "list" to see all 11 sub-tools and their current enabled/disabled state, or action: "update" with an enabled_tools array to change which ones are active. Each connected app gets its own configuration.
Tool Permissions & Consent
When a new client connects via OAuth, you see a Google-style consent screen where you choose exactly which memory sub-tools to grant access to. Each client gets its own independent configuration — you might give Cursor full access to your knowledge graph and files, while a different app only gets conversation history search.
The 11 sub-tools are grouped into three layers:
Knowledge Graph (5 tools)
Entity search, temporal facts, behavioral signals, user profile, store knowledge
Data Sources (5 tools)
Conversation history, emails, financial data, social media, cloud files
Multimodal (1 tool)
Cross-modal identity matching (premium only)
Managing Connected Apps
Go to Data Platform > API & Monetization to see all external apps that have been granted access to your memory layer. Each connected app shows:
App name and connection date
Number of active sessions
Last used date
Click Revoke to immediately disconnect an app and invalidate all its tokens. The app will need to re-authorize through the OAuth flow to regain access.
Credit Billing
External MCP tool calls that run LLM agents (like unified_memory_agent) are billed based on actual token usage. The same per-model pricing as chat applies, with no free input token allowance. Tools that don't run LLMs (like unified_memory_agent_config) are free.
Internal calls from the Cognitia web and mobile apps are not double-billed — credit deduction only applies when the request comes from an external OAuth client.
A rate limit of 60 requests per minute is applied per user across all MCP endpoints to prevent abuse.
Technical Architecture
When an external client calls unified_memory_agent, the request flows through several layers:
Authentication — The MCP endpoint validates the OAuth access token (or JWT fallback), extracting the user ID and client ID.
Rate Limit Check — A sliding-window counter ensures the user hasn't exceeded 60 requests/minute.
Config Lookup — The server loads the per-client tool configuration (which sub-tools this app is allowed to use) and the user's subscription tier.
Agent Execution — An internal LLM agent (GPT-5.4 Mini) receives the query and a dynamically-built toolset containing only the enabled sub-tools. It runs up to 6 steps, calling sub-tools in parallel when appropriate.
Sub-tool Execution — Each sub-tool dispatches to the appropriate backend: Supabase (knowledge graph), Pinecone (semantic search, emails, files, financial, social), or the multimodal embedding store.
Billing — Total input and output tokens from all LLM calls are accumulated. Credits are calculated and deducted (external OAuth clients only).
The response includes a synthesized context summary, structured entities/facts/signals, the tools that were used, and the number of steps taken. Token usage metadata is stripped before the response reaches the client.
API Endpoints
All endpoints are served from the base URL https://cognitia.co/api/mcp. The server supports both the JSON-RPC 2.0 protocol and direct REST-style routes.
MCP Protocol (JSON-RPC 2.0)
/api/mcp/jsonrpc
JSON-RPC endpoint (all MCP methods)
/api/mcp/tools/list
List available tools
/api/mcp/tools/call
Execute a tool
/api/mcp/resources/list
List available resources
/api/mcp/resources/read
Read a specific resource
/api/mcp/prompts/list
List available prompts
/api/mcp/prompts/get
Get a prompt with arguments
OAuth 2.1 Endpoints
/.well-known/oauth-authorization-server
Server metadata (RFC 8414)
/api/mcp/oauth/register
Dynamic client registration
/api/mcp/oauth/authorize
Authorization (redirects to consent)
/api/mcp/oauth/token
Token exchange and refresh
/api/mcp/oauth/connected-apps
List connected apps
/api/mcp/oauth/connected-apps
Revoke app access
OAuth 2.1 Flow Detail
The authorization flow follows the OAuth 2.1 Authorization Code grant with PKCE (S256). Most MCP clients handle this automatically — the details below are for client developers and advanced users.
Discovery — The client fetches /.well-known/oauth-authorization-server to discover endpoints and supported capabilities.
Client Registration — The client registers itself via POST /api/mcp/oauth/register with its name and redirect URIs. Returns a client_id.
Authorization — The client generates a PKCE code_verifier/code_challenge pair and redirects the user to the authorization endpoint with response_type=code, code_challenge_method=S256, and the code_challenge.
Consent — The user logs into Cognitia (if not already), sees the tool permission screen, selects which tools to grant, and clicks Allow Access.
Code Exchange — The server redirects back to the client with an authorization code. The client exchanges it at POST /api/mcp/oauth/token with the code_verifier.
Token Response — Returns an access token (1 hour TTL) and refresh token (90 day TTL). The client uses the access token in the Authorization: Bearer header for all MCP requests.
Refresh — When the access token expires, the client exchanges the refresh token at the token endpoint for a new access/refresh token pair. Refresh tokens are rotated on each use.
Token Formats
OAuth access token — 64-character hex, 1-hour TTL, stored as SHA-256 hash
OAuth refresh token — 64-character hex, 90-day TTL, rotated on each use
Supabase JWT (fallback) — standard JWT, 1-hour TTL, no auto-refresh
Input & Output Schemas
unified_memory_agent — Input
{ "query": "string (required) — natural language query", "context_hint": "string (optional) — e.g. 'relationships', 'timeline', 'emails', 'files', 'financial', 'identity'" }
unified_memory_agent — Output
{ "success": true, "context": "Synthesized text summary of findings...", "entities": [ { "name": "...", "type": "person|org|place|...", "mentionCount": 5, "lastSeen": "2026-02-19T..." } ], "temporalFacts": [ { "type": "state|event|preference", "subject": "...", "predicate": "...", "object": "...", "validAt": "...", "confidence": 0.95 } ], "profileSignals": [ { "category": "preference|habit|style|...", "key": "...", "value": "...", "confidence": 0.8 } ], "sources": ["search_entities", "search_emails"], "reasoning": "Queried 2 sources in 3 steps (420ms)", "stepsTaken": 3, "multimodalEnabled": false, "enabledTools": ["search_entities", "search_emails", ...] }
unified_memory_agent_config — Input (list)
{ "action": "list" }
unified_memory_agent_config — Output (list)
{ "tools": [ { "name": "search_entities", "label": "Entity & Relationship Search", "layer": "knowledge_graph", "enabled": true, "requiresPremium": false, "available": true } ], "isPremium": false, "updatedAt": "2026-02-19T..." }
unified_memory_agent_config — Input (update)
{ "action": "update", "enabled_tools": [ "search_entities", "search_temporal", "search_emails" ] }
unified_memory_agent_config — Output (update)
{ "success": true, "enabledTools": ["search_entities", "search_temporal", "search_emails"], "updatedAt": "2026-02-19T..." }
Error Responses
All MCP endpoints return standard HTTP status codes. The 401 response includes a WWW-Authenticate header pointing to the authorization server metadata, allowing clients to auto-discover the OAuth flow.
Success — tool result in response body
Bad request — missing or invalid parameters
Unauthorized — invalid/expired token. Includes WWW-Authenticate: Bearer resource_metadata="..." header
Forbidden — user ID mismatch
Method not allowed — wrong HTTP method
Rate limited — includes Retry-After: 60 header. Wait and retry.
Internal server error
Rate Limits & Billing Detail
Rate Limits
Requests per minute
60 per user (sliding window)
Auth code TTL
5 minutes (single use)
Access token TTL
1 hour
Refresh token TTL
90 days (rotated on each use)
Agent max steps
6 LLM calls per query
CORS
All origins allowed (Access-Control-Allow-Origin: *)
Using AI Agents
Multi-Agent Orchestration
When you send a message, Cognitia's orchestrator analyzes your request and determines which tools and agents are needed. For complex requests, it breaks the task into parallel operations:
Automatic tool selection: Cognitia picks the right tools based on your connected integrations and the nature of your request.
Parallel execution: Independent tasks run simultaneously. For example, searching emails while checking your calendar happens at the same time.
Context awareness: The orchestrator uses your conversation history, user directives, and persistent memory to provide personalized responses.
Browser Automation
Cognitia can browse the web on your behalf using a server-side browser agent. This agent can navigate pages, click buttons, fill forms, extract data, and complete multi-step flows like making reservations or signing up for services.
Available browser actions:
Navigate to URLs
Click elements
Fill forms
Extract page data
Take screenshots
Multi-step flows
Workflow Agents
For complex multi-step tasks, Cognitia can create persistent workflow agents that track progress across steps, maintain state, and report back when complete. These agents use a built-in todo and memory system to break down large tasks into manageable steps and execute them sequentially or in parallel.
Document Generation
Generate professional documents directly from your conversations. Cognitia can create files in multiple formats and optionally upload them to your connected cloud storage.
Understanding Credits
Cognitia uses a credit-based system to manage usage. Each message, tool call, and AI model interaction consumes credits based on the complexity and model used. Your subscription tier determines your monthly credit allocation.
Different models, different costs: More powerful models (like GPT-5.4 or Claude Opus 4.6) use more credits per message than lighter models.
Tool calls count: When Cognitia uses tools (email search, browser automation, etc.), each tool invocation adds to the credit cost of that message.
Track your usage: Monitor your credit balance in your Account settings.