Skip to main content

Connecting to DreamSolve MCP Server

DreamSolve provides a Model Context Protocol (MCP) server that allows AI assistants like Claude to interact directly with your projects and tasks. This guide explains how to connect various MCP clients to DreamSolve.

What is MCP?​

The Model Context Protocol is an open standard that enables AI assistants to securely connect to external tools and data sources. With MCP, Claude can:

  • Create new projects and tasks in DreamSolve
  • Parse plans and generate task lists automatically
  • Assign tasks to team members
  • Access your project context during conversations
  • Manage files associated with nodes
  • Search and analyze your organization's data

The preferred way to connect to DreamSolve is through the DreamSolve skill available in the Difflab Marketplace. Install the skill and follow its setup instructions for pre-configured access to all DreamSolve MCP tools.

The sections below describe manual MCP server configuration for advanced use cases.

Connecting Claude Desktop​

The easiest way to connect Claude Desktop to DreamSolve is through the built-in connector settings.

  1. Open Claude Desktop Settings

    • Click the Claude menu in the menu bar
    • Select Settings

  2. Add Custom Connector

    • Navigate to the Connectors section
    • Click Add Custom Connector

  3. Configure DreamSolve

    • Name: DreamSolve
    • URL: https://dreamsolve.ai/api/mcp/server
    • Click Save

  4. Authenticate

    • Claude Desktop will open a browser window
    • Sign in to DreamSolve using your preferred method (Google, GitHub, or email)
    • After authentication, you'll be redirected back to Claude Desktop

  5. Start Using DreamSolve

    • You can now ask Claude to create projects, tasks, and manage your work in DreamSolve

Manual Configuration​

If you prefer to edit the configuration file directly:

  1. Locate the config file

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the DreamSolve configuration

    For production:

    {
      "mcpServers": {
        "dreamsolve": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://dreamsolve.ai/api/mcp/server"
          ],
          "env": {}
        }
      }
    }

    For local development:

    {
      "mcpServers": {
        "dreamsolve": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "http://localhost:3000/api/mcp/server"
          ],
          "env": {}
        }
      }
    }

  3. Restart Claude Desktop

    • Quit and reopen Claude Desktop for the changes to take effect

  4. Complete OAuth Authentication

    • When you first use a DreamSolve tool, Claude will prompt you to authenticate
    • Follow the browser prompts to sign in

Available MCP Tools​

Once connected, Claude has access to these DreamSolve tools:

Organization Context​

All tools operate within an organization context. By default, the user's selected organization is used.

listOrganizations​

List all organizations the user is a member of.

Parameters: None

getSelectedOrganization​

Get the currently selected organization (used by default for all tool calls).

Parameters: None

Overriding the Organization​

Every tool accepts an optional organizationId parameter to override the default organization for that call. Use listOrganizations to find available organization IDs.

{
  "name": "searchNodes",
  "arguments": {
    "query": "onboarding",
    "organizationId": "org-abc123"
  }
}

Node Tools​

createNode​

Create a node of any supported type.

Required: type, name Optional: description, parentId, containerId, status, data, organizationId

Supported types: Action, Agent, AgentScope, Assignment, BusinessUnit, Company, Context, Decision, Delta, Experiment, File, Hypothesis, Issue, KnowledgeTuple, Log, Memory, Module, Package, Person, Problem, Project, Resource, Task, Team.

Example conversation:

"Create a new project called 'Website Redesign' with the goal of launching a modern, responsive website by Q2"

readNode​

Read a node's full details by ID.

Required: nodeId Optional: includeChildren, organizationId

updateNode​

Update an existing node's fields.

Required: nodeId Optional: name, description, status, parentId, containerId, data, organizationId

listChildNodes​

List direct children of a node.

Required: nodeId Optional: includeTypes (array of type strings), organizationId

searchNodes​

Search nodes by name, type, status, or text query.

Optional: query, type, status, parentId, containerId, limit (default 50, max 200), organizationId

createTasksFromPlan​

Use an LLM to parse plan text and create sub-nodes within a parent node.

Required: nodeId, plan Optional: nodeType, organizationId

Example conversation:

"Here's my plan for the project:

  1. Research competitor websites
  2. Create wireframes
  3. Design high-fidelity mockups
  4. Develop frontend
  5. Test and launch

Please create tasks from this plan"

assignTask​

Assign a task to a team member.

Required: taskId Optional: assigneeId, assigneeName, organizationId

Example conversation:

"Assign the wireframe task to Sarah"

determineSuitability​

Analyze child nodes for AI suitability using the GenAI Tractability Grid.

Required: nodeId Optional: includeTypes, organizationId

File Tools​

searchFiles​

Search files associated with a node across all providers (internal, Google Drive, public URL).

Required: nodeId, query Optional: organizationId

readFile​

Read file content or get a download URL. Files ≤ 1MB return content directly; larger files return a download URL. Internal files are scanned for malware before they can be read.

Required: nodeId, fileId Optional: organizationId

createFile​

Create a file and associate it with a node. Text content can be provided directly; binary files receive a presigned upload URL. Files are scanned for malware after creation.

Required: nodeId, name Optional: description, content, mimeType, organizationId

updateFile​

Update file metadata or content. Content updates only work for internal (S3) files.

Required: nodeId, fileId Optional: name, description, content, organizationId

deleteNode​

Delete a node and all its children (soft delete). The node and its descendants are marked as deleted and no longer appear in search results. This operation is recursive.

Required: nodeId

Agent Tools​

searchAgents​

Search for available AI agents. With no parameters, lists all agents. Use query to search by name or description, and category to filter by category. Returns agent details including ID, name, description, category, capabilities, and execution environment. Use this to discover agents before calling executeAgent.

Optional: query, category

Example conversation:

"What agents are available for research?"

executeAgent​

Execute an AI agent to perform a task. Agents can operate in conversational mode (general chat) or node-assignment mode (focused on a specific node/task). When the agent is working on a subject described by a node, pass a nodeId to use node-assignment mode.

Required: agentId, mode, userInput Optional: nodeId, conversationId

Modes:

ModeDescription
conversationalGeneral conversation with the agent
node-assignmentAgent works on a specific node (requires nodeId)

Example conversation:

"Run the Research agent on my Website Redesign project to analyze competitors"

askUserQuestion​

Ask the user a clarifying question during agent execution. The execution pauses and waits for the user's response before continuing.

Required: question Optional: options (array of {label, value, description?}), allowFreeInput

Example Workflow​

Here's how a typical conversation with DreamSolve MCP might look:

You: "I need to plan a mobile app development project. The goal is to launch an iOS and Android app for fitness tracking by the end of the year."

Claude: "I'll create a new project in DreamSolve for you."

[Claude uses createProject tool]

"I've created the 'Mobile Fitness App' project. Would you like me to break this down into tasks?"

You: "Yes, please create tasks for:

  • User research and requirements
  • UI/UX design
  • Backend API development
  • iOS app development
  • Android app development
  • Testing and QA
  • App store submission"

Claude: "Creating those tasks now..."

[Claude uses createTasksFromPlan tool]

"Done! I've created 7 tasks in your Mobile Fitness App project. You can view and manage them in DreamSolve."

Requirements​

  • DreamSolve Account: You need a DreamSolve account to use MCP features
  • Organization Membership: You must be a member of at least one organization
  • Node.js: Required for the npx mcp-remote command (included with most development environments)

Troubleshooting​

"Connection failed" error​

  • Ensure you have an active internet connection
  • For local development, ensure DreamSolve is running (npm run dev)
  • Check that Node.js is installed (node --version)
  • Try using 127.0.0.1 instead of localhost in the URL
  • Try restarting Claude Desktop

Authentication issues​

  • Clear your browser cookies for dreamsolve.ai and try again
  • Make sure you're signing in with the correct account
  • Check that you have organization membership in DreamSolve
  • Supabase session tokens are also accepted as Bearer tokens

Tools not appearing​

  • Restart Claude Desktop after adding the configuration
  • Verify the configuration file syntax is valid JSON
  • Check the Claude Desktop logs for error messages

OAuth token expired​

OAuth tokens expire after 1 hour. If you encounter authentication errors:

  • Claude Desktop will automatically prompt you to re-authenticate
  • Simply follow the browser prompts to sign in again

OAuth redirect errors​

If you're experiencing OAuth redirect issues, use npx mcp-remote which handles the OAuth flow automatically.

SSE transport errors​

The server supports both HTTP and SSE (Server-Sent Events) transports. If one doesn't work, the client should automatically fall back to the other.

Other MCP Clients​

The DreamSolve MCP server works with any MCP-compatible client. Use the following endpoint:

https://dreamsolve.ai/api/mcp/server

The server supports:

  • OAuth 2.0 authentication with dynamic client registration
  • HTTP transport
  • SSE (Server-Sent Events) transport

Authentication Flow​

The MCP server uses OAuth 2.0 with dynamic client registration:

  1. Register - POST /api/mcp/register registers a new OAuth client
  2. Authorize - GET /api/mcp/oauth initiates the OAuth flow
  3. Token Exchange - POST /api/mcp/oauth exchanges an auth code for an access token
  4. API Access - Pass the token as Authorization: Bearer <token>

Supabase session tokens are also accepted as Bearer tokens.

Dynamic Client Registration​

MCP clients can register dynamically:

curl -X POST https://dreamsolve.ai/api/mcp/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["http://localhost:8080/callback"],
    "scope": "read:projects write:tasks",
    "grant_types": ["authorization_code"],
    "response_types": ["code"]
  }'

Testing with curl​

You can test the MCP server directly using curl:

# Initialize connection (no auth required)
curl -X POST https://dreamsolve.ai/api/mcp/server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}'

# List tools
curl -X POST https://dreamsolve.ai/api/mcp/server \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

# Call a tool
curl -X POST https://dreamsolve.ai/api/mcp/server \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "listOrganizations",
      "arguments": {}
    }
  }'

For local development, replace https://dreamsolve.ai with http://localhost:3000 (or http://127.0.0.1:3000 if localhost doesn't work).

Connecting an External Agent​

External AI agents (Claude Code, Cursor, or custom MCP clients running autonomously) can register with a DreamSolve organization using an Ed25519 key pair instead of the browser-based OAuth flow.

1. Generate a Key Pair​

The agent generates an Ed25519 key pair and stores the private key securely. For example, in Node.js:

import { generateKeyPairSync } from 'crypto';

const { publicKey, privateKey } = generateKeyPairSync('ed25519');
const rawPublicKey = publicKey.export({ type: 'spki', format: 'der' }).subarray(-32);
const base64urlKey = rawPublicKey.toString('base64url');

2. Construct the Registration URL​

Build the URL and share it with a human user who has access to the target organization:

https://dreamsolve.ai/invitations/agent/organization/<ORG_ID>/register?pk=<BASE64URL_PUBLIC_KEY>&name=<AGENT_NAME>
  • ORG_ID - The target organization ID
  • pk - The 32-byte Ed25519 public key, base64url-encoded (no padding)
  • name - A human-readable name for the agent (optional)

3. Human Approves Registration​

The human user follows the link, signs in, reviews the agent name and key fingerprint, selects a role (member or viewer), and approves. The page displays the agentUserId which the human shares back with the agent.

4. Authenticate​

The agent signs a JWT with its private key and exchanges it for bearer tokens:

# The JWT must have:
#   Header: { "alg": "EdDSA", "typ": "JWT" }
#   Payload: { "sub": "<agentUserId>", "iat": <now>, "exp": <now + 5min> }
#   Signature: Ed25519 signature with the agent's private key

curl -X POST https://dreamsolve.ai/api/v1/agents/auth/token \
  -H "Content-Type: application/json" \
  -d '{ "agent_jwt": "<signed_jwt>" }'

Returns access_token (1 hour, mcp_ prefix) and refresh_token (30 days, mcpr_ prefix).

5. Make MCP Tool Calls​

Use the access token as a Bearer token on the MCP server endpoint:

curl -X POST https://dreamsolve.ai/api/mcp/server \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "searchNodes",
      "arguments": { "query": "my project" }
    }
  }'

6. Refresh Tokens​

Before the access token expires, refresh it:

curl -X POST https://dreamsolve.ai/api/v1/agents/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "<refresh_token>" }'

Deactivation​

When an agent is removed from an organization (via organization settings), its key is automatically deactivated. The agent can be re-registered with a new key pair.

Security​

  • All MCP connections use OAuth 2.0 or agent key pair authentication
  • Tokens are scoped to your DreamSolve account and organization
  • DreamSolve respects your existing permissions and access controls
  • You can revoke MCP access at any time from your DreamSolve settings
  • Agent JWT timestamps must be within 5 minutes of server time
  • Removing an agent from an organization immediately deactivates its key

Next Steps​