MCP — Model Context Protocol

The Model Context Protocol (MCP) is an open standard that lets AI applications dynamically connect to external tools and data sources. Yukkai has built-in MCP support, meaning any MCP-compatible server you add instantly extends Yukkai's capabilities — no code changes, no app updates required.

What MCP Does

MCP defines a standard protocol for servers to expose their tools to AI clients. Instead of Yukkai hard-coding support for every possible service, MCP lets you connect any server that implements the protocol. Once connected, the server's tools are automatically registered in Yukkai's ToolRegistry and become available to the AI in conversation.

Key Benefits

• Plug-and-play — Add a server and its tools are immediately available
• No code changes — Everything is dynamic, registered at runtime
• Standard protocol — Works with any MCP-compatible server (community or custom)
• Secure by design — Secrets are referenced via Vault placeholders, never written in plaintext

Supported Transports

Yukkai supports three transport types for connecting to MCP servers:

Transport	Use Case	Example
stdio	Local servers spawned as child processes	npx -y @modelcontextprotocol/server-filesystem /Users/me/Documents
SSE	Remote servers using Server-Sent Events	http://localhost:3001/sse
Streamable HTTP	Remote servers using HTTP streaming	https://my-server.example.com/mcp

Choose the transport based on where the server actually runs — stdio for local processes, SSE or HTTP for remote/shared servers.

Managing MCP Servers

Adding a Server

Stdio (local process):

manage_mcp_servers(
  action: "add",
  name: "filesystem",
  transport: "stdio",
  command: "npx",
  arguments: "-y @modelcontextprotocol/server-filesystem /Users/me/Documents"
)

SSE (remote):

manage_mcp_servers(
  action: "add",
  name: "brave-search",
  transport: "sse",
  url: "http://localhost:3001/sse"
)

With environment variables (secrets):

manage_mcp_servers(
  action: "add",
  name: "github-mcp",
  transport: "stdio",
  command: "npx",
  arguments: "-y @modelcontextprotocol/server-github",
  env: "{\"GITHUB_TOKEN\":\"{{VAULT:github}}\"}"
)

⚠️ Never put raw API keys in the env parameter. Always use {{VAULT:service}} placeholders to reference secrets stored in the macOS Keychain. The actual value is resolved client-side and never visible to the LLM.

Other Actions

Action	Description
list	Lists all configured servers with their connection status
test	Tests the connection to a specific server
connect	Manually connects a disconnected server
disconnect	Manually disconnects a server
toggle	Enables or disables a server
remove	Removes a server entirely

How MCP Tools Work

Once an MCP server is connected, its tools are automatically registered with the naming pattern:

mcp_<serverName>_<toolName>

For example, a "filesystem" server exposing a read_file tool registers as:

mcp_filesystem_read_file

These tools behave identically to Yukkai's native tools — they're exposed to the LLM via JSON Schema, protected by security gates, and can be called directly in conversation.

Best Practices

1. Always list before using — Servers can be disconnected between sessions. Never assume a tool from a past session is still available.
2. test after add — Confirm the connection works before relying on the server's tools.
3. Use Vault for secrets — Reference API keys as {{VAULT:service}}, never as raw strings.
4. Check the server's docs — Different servers use different transports (stdio vs SSE vs HTTP). Verify before adding.

Popular MCP Servers

These are commonly used MCP servers that work out of the box with Yukkai:

Server	Description	Transport
@modelcontextprotocol/server-filesystem	File read/write access to specified directories	stdio
@modelcontextprotocol/server-brave-search	Web search via Brave Search API	stdio
@modelcontextprotocol/server-github	GitHub API access (issues, PRs, repos)	stdio
@modelcontextprotocol/server-slack	Slack API (messages, channels)	stdio
@modelcontextprotocol/server-postgres	PostgreSQL database queries	stdio

You can find more community servers on the MCP servers registry.

Security

MCP servers run with the same security guarantees as native Yukkai tools:

• PathGuard intercepts any file paths involved in MCP tool calls
• SecretDetector masks secrets in responses
• InjectionDetector prevents prompt injection from external data
• LLMController validates tool call consistency with user intent

MCP servers spawned via stdio run as child processes of Yukkai — they inherit the app's permissions and sandbox.