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
2. Discovery lists tools when you save, refresh, or sign in (Settings → Plugins → MCP)
3. Chat start uses the cached tool catalog — it does not connect
4. A live session starts when the agent first calls a tool on that server

Configuring MCP Servers

Via Settings UI

Configure MCP servers from Settings → Plugins → MCP:

1. Open Settings → Plugins → MCP
2. Click Add Server or browse the marketplace for popular servers
3. Edit server configuration — command, args, environment variables, or remote URL
4. Save — Tarsk connects once to list tools and stores them. A new chat can use those tools without connecting first.

Tarsk prefers .agents/mcp.json in the project root, falling back to mcp.json if present.

Project-Level Configuration

MCP servers belong to the selected project. In Settings, you edit the configuration in that project’s canonical checkout. Thread sessions read the configuration from their own working-copy directories. Tarsk links active thread paths to their owning project to share the tool catalog and OAuth credentials. For a path outside a registered project, Tarsk uses that path as its own scope.

Settings saves and workspace copies

Saving or removing a server in Settings → Plugins → MCP writes the full server configuration to the canonical checkout and mirrors it to the project’s existing active thread working copies. An API save or removal targeting an active working copy also updates the canonical checkout and sibling copies. Tarsk keeps each copy’s existing configuration file location, preferring .agents/mcp.json over mcp.json, and creates .agents/mcp.json if neither exists. Tarsk skips missing working-copy directories and logs mirror failures without failing the primary save.

Hand edits affect the file you edit; they do not trigger mirroring or tool discovery. A later Settings save or removal can overwrite workspace-only server changes because Tarsk mirrors the full configuration, not a per-server patch. Use Settings to keep copies aligned. Refresh updates the tool catalog without copying configuration files.

Global Configuration

There is no global MCP configuration. Servers configured in Settings → Plugins → MCP belong to the currently selected project. Select a different project to configure its servers.

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 a local stdio server
args	string[]	Required for local stdio servers; use [] when the command needs no arguments
env	object	Environment variables for the local server process
defer	boolean	When true (default), tool schemas stay behind tool_search until the agent needs them. Set false to always inject this server’s tools into the initial prompt.

Toggle Deferred per server in Settings → Plugins → MCP → Edit server. Leave it on unless those tools are needed in nearly every conversation. To use a deferred server, mention it by name in the prompt; the agent loads its tools with tool_search for that turn.

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_PERSONAL_ACCESS_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

After discovery, the agent can load deferred MCP tools with tool_search and call them:

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. For OAuth remote servers without Dynamic Client Registration (e.g. GitHub Copilot MCP), add your OAuth App client ID and client secret, then click Sign in
4. Save configuration

Remote OAuth servers open a browser login and store tokens encrypted. Token-based remotes can still use headers or URL query tokens.

Refreshing the Tool Catalog

After a Settings save, Refresh, or OAuth sign-in, Tarsk connects to the server, lists its tools, stores the result, and closes the discovery connection. At chat start, Tarsk loads cached tools without connecting. Active working copies share a catalog entry per project and server name.

Tarsk checks a fingerprint of command, args, server env, url, transport, headers, oauth, and timeout against the cached entry. If your hand edits change that fingerprint, Tarsk withholds that server’s cached tools until discovery succeeds for the new configuration. Use Refresh after editing the canonical configuration. Changing defer does not invalidate the catalog.

Project environment variables are outside that fingerprint. After changing them, use Refresh if they affect authentication or which tools the server exposes. Saving configuration does not restart live connections in other working copies, so do not assume those sessions have picked up new credentials.

Keep working-copy configurations aligned before refreshing. If two copies use different fingerprinted settings for the same server name, discovery from one copy replaces the shared catalog entry and leaves the other copy’s catalog stale.

Troubleshooting connections

Run the server command manually in a terminal to verify it starts, authenticates, and exposes tools:

npx -y @modelcontextprotocol/server-filesystem /path/to/files

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"
    }
  }
}

Environment Variables

For local stdio servers, add shared secrets under Settings → Variables for the selected project. Tarsk decrypts those project values when connecting for discovery or tool use, including from active thread working copies.

The local server’s environment uses this precedence, from lowest to highest:

1. The MCP SDK’s limited inherited environment, such as PATH (and HOME on macOS/Linux).
2. The project’s environment variables.
3. The server’s env values in the MCP configuration.

For example, a server-level DATABASE_URL overrides the project value; other project variables remain available to that server. Do not rely on arbitrary shell exports reaching the process. Values you put in the configuration’s env object remain plaintext in that file and its mirrored copies.

Remote SSE and Streamable HTTP connections do not receive this environment merge. Configure remote authentication through OAuth or headers. Tarsk does not expand environment-variable placeholders such as ${API_TOKEN} in MCP configuration values, including URLs and headers.

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. Open Settings → Plugins → MCP and confirm the server shows a tool count (use Refresh if it says “Refresh to load tools”)
2. Check server configuration syntax
3. Ensure tools are properly exported by server
4. Sign in if the row says sign-in is required

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";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

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

server.setRequestHandler(ListToolsRequestSchema, async function listTools() {
  return {
    tools: [
      {
        name: "my_custom_tool",
        description: "Return a test message",
        inputSchema: { type: "object", properties: {} },
      },
    ],
  };
});

// Register a tool handler
server.setRequestHandler(CallToolRequestSchema, async function callTool(request) {
  if (request.params.name === "my_custom_tool") {
    return {
      content: [
        {
          type: "text",
          text: "Tool executed successfully",
        },
      ],
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// 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.