Integrations (MCP)

Model Context Protocol (MCP) lets you connect external tools, databases, and data sources to Tarsk. MCP servers provide additional capabilities that the AI agent can use during conversations.

What MCP Enables

MCP servers can give your AI agent access to:

• External databases (PostgreSQL, MongoDB, Redis)
• File systems (local directories, cloud storage)
• APIs and services (GitHub, Slack, Jira)
• Development tools (Docker, Kubernetes, CI/CD)
• Custom business logic (internal APIs, proprietary tools)

How MCP Works in Tarsk

1. Configure servers in project settings or globally
2. Servers start when a thread is created
3. Agent discovers available tools from connected servers
4. Tools appear alongside built-in agent tools
5. Agent calls MCP tools during conversations

Configuring MCP Servers

Project-Level Configuration

Configure MCP servers for a specific project:

1. Open project settings
2. Go to Integrations → MCP Servers
3. Click Add Server
4. Enter server configuration

Global Configuration

Configure servers available to all projects:

1. Go to Settings → MCP Servers
2. Add server configuration
3. These servers will be available in all projects

Server Configuration Format

MCP servers use this configuration format:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {
        "ALLOWED_DIRECTORIES": "/Users/username/projects"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

Configuration Fields

Field	Type	Description
command	string	Command to start the server
args	string[]	Arguments passed to the command
env	object	Environment variables for the server
cwd	string	Working directory (optional)

Popular MCP Servers

File System Access

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "ALLOWED_DIRECTORIES": "/Users/username/projects"
    }
  }
}

Tools provided: read_file, write_file, list_directory, search_files

PostgreSQL Database

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
    }
  }
}

Tools provided: execute_query, list_tables, get_schema

GitHub Integration

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
    }
  }
}

Tools provided: create_issue, list_issues, get_repo, create_pr

Slack Integration

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_TOKEN": "xoxb-xxxxxxxxxxx"
    }
  }
}

Tools provided: send_message, list_channels, get_history

Using MCP Tools in Conversations

Once configured, MCP tools appear automatically:

User: "What are the open issues in our GitHub repo?"

Agent: "I'll check the GitHub issues for you."

[Tool call: list_issues with github MCP server]

Agent: "I found 5 open issues in the repository..."

Managing MCP Servers

Adding a Server

1. Click Add Server in MCP settings
2. Choose from popular servers or enter custom configuration
3. Test connection
4. Save configuration

Testing Configuration

Use the Test Connection button to verify:

• Server starts successfully
• Authentication works
• Tools are discoverable
• Permissions are correct

Removing a Server

1. Find server in MCP settings
2. Click Remove
3. Confirm deletion

Security Considerations

Principle of Least Privilege

Only grant necessary permissions:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/specific/project/folder"],
    "env": {
      "ALLOWED_DIRECTORIES": "/specific/project/folder" // Not entire filesystem
    }
  }
}

Environment Variables

• Store sensitive data in environment variables
• Never hardcode API keys in configuration
• Use secure token storage when possible

Network Access

MCP servers run with the same network access as Tarsk. Consider:

• Firewall rules for external API calls
• VPN requirements for corporate resources
• Proxy configuration if needed

Troubleshooting

Server Won’t Start

Check configuration:

# Test server command manually
npx -y @modelcontextprotocol/server-filesystem /path/to/files

# Check environment variables
echo $DATABASE_URL

Common issues:

• Missing dependencies
• Incorrect environment variables
• Permission denied paths
• Network connectivity issues

Tools Not Appearing

1. Verify server is running in thread logs
2. Check server configuration syntax
3. Ensure tools are properly exported by server
4. Restart thread to reload MCP servers

Authentication Failures

1. Verify API tokens are valid
2. Check token permissions
3. Ensure environment variables are set correctly
4. Test with external tools first

Building Custom MCP Servers

Create your own MCP servers for proprietary tools:

Basic Server Structure

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0",
});

// Register a tool
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "my_custom_tool") {
    return {
      content: [
        {
          type: "text",
          text: "Tool executed successfully",
        },
      ],
    };
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Package.json

{
  "name": "@myorg/mcp-server-custom",
  "version": "1.0.0",
  "bin": {
    "mcp-server-custom": "./dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"
  }
}

Configuration in Tarsk

{
  "my-custom-server": {
    "command": "npx",
    "args": ["-y", "@myorg/mcp-server-custom"],
    "env": {
      "API_ENDPOINT": "https://api.mycompany.com"
    }
  }
}

Best Practices

1. Start small - Begin with file system or database access
2. Test locally - Verify servers work before integrating
3. Use environment variables - Keep secrets out of configuration
4. Monitor usage - Check agent tool usage patterns
5. Document tools - Keep clear documentation of available tools
6. Version control - Track MCP configurations in git

Example Use Cases

Database-Backed Development

Configure PostgreSQL MCP server to let agents:

• Query existing data structures
• Generate migrations based on schema
• Create test data
• Analyze query performance

CI/CD Integration

Configure GitHub and CI/CD MCP servers to:

• Create pull requests for changes
• Check CI status
• Deploy to staging environments
• Monitor production health

Internal API Access

Create custom MCP server for internal APIs to:

• Fetch user data
• Update inventory
• Generate reports
• Validate business rules

MCP transforms Tarsk from a code editor into a comprehensive development environment with access to all your tools and data sources.