Skip to main content

​
What is MCP

Model Context Protocol (MCP) is an open standard that connects AI applications to external data sources and tools. It defines how AI clients discover capabilities, authenticate with servers, and execute operations through a standardized interface. Poke acts as an MCP host - when users add an integration, Poke connects to your MCP server, discovers available tools, and makes them available to AI agents during conversations. Read the official specification for complete protocol details.

​
How Poke Implements MCP

Poke builds on the official MCP TypeScript SDK and acts as the MCP client. Your integration runs as a remote MCP server exposed via HTTPS. Integration flow:
  1. Users add your server URL in Settings → Integrations
  2. Poke connects and negotiates protocol version with your server
  3. If authentication is required, users provide credentials (API key) or authorize via OAuth
  4. Poke establishes authenticated connection
  5. Your server returns metadata and available tools
  6. Poke caches tools and makes them available to agents
  7. Agents can call your tools as needed during conversations
See MCP Client Specification for detailed implementation requirements.

​
What Matters Most

Building a great integration comes down to two things:

​
1. Server Instructions (Critical)

This is the most important part of your integration. Server instructions guide how Poke’s AI agents decide when and how to use your tools. Think of them as the “system prompt” for your integration. Poor instructions = agents won’t use your tools correctly, no matter how well-designed they are. See Server Instructions for comprehensive guidance - this is worth reading carefully.

​
2. Tool Design (Important)

Tools should have clear names, comprehensive descriptions, and well-defined schemas. Agents use these to understand what your tools do. See Tool Design Philosophy for best practices.
Everything else (protocol versions, transport layers, authentication flows) is typically handled by frameworks like FastMCP. If you’re building from scratch, the sections below explain what you need to implement.

​
Protocol Support

Poke supports the latest MCP protocol versions and automatically negotiates the highest mutually supported version during connection. Your server should implement at least one supported protocol version. Modern frameworks like FastMCP handle protocol negotiation automatically - you don’t need to think about this.
Poke uses MCP SDK v1.17.3, supporting protocol versions 2025-06-18 (latest) and 2024-11-05 (backward compatibility). The default negotiated version is 2025-03-26.See MCP Client Specification for specific version requirements.

​
Server Metadata

During initialization, your server provides metadata that helps Poke understand your integration:
  • name - Server identifier (shown to agents in tool calls)
  • version - Version string (not displayed to users)
  • title - Optional human-readable name (shown in UI)
  • instructions - Critical: Guides agents on how to use your tools
Example: 
{
  "name": "github-integration",
  "version": "1.0.0",
  "title": "GitHub",
  "instructions": "Use this integration to manage GitHub repositories, issues, and pull requests. Always search for repositories before creating issues. When creating PRs, fetch the latest branch status first to avoid conflicts."
}
The instructions field is where you teach agents how to use your integration effectively. Don’t skip this - it’s more important than any individual tool description. See Server Instructions for how to write effective instructions.

​
Capabilities

Poke supports these MCP protocol capabilities:
FeatureSupportDescription
ToolsSupportedFunctions for the AI model to execute
PromptsNot SupportedTemplated messages and workflows for users
ResourcesNot SupportedStructured data sources that can be read and referenced
RootsNot SupportedServer-initiated inquiries into URI or filesystem boundaries
ElicitationNot SupportedServer-initiated requests for additional information from users
Currently, Poke only uses the Tools capability. Your server can safely expose other capabilities, but Poke won’t call them. Focus your effort on tools and instructions.

​
Tools

Tools are the core of integrations - they’re functions that AI agents can call to interact with your service.

​
Discovery and Execution

When users add your integration:
  1. Poke calls tools/list to discover available tools and their schemas
  2. Tools are cached for the session duration
  3. During conversations, agents can call tools/call to execute your tools
  4. Tool results are returned to the agent for further processing
See Tool Lifecycle for details on discovery, caching, and updates.

​
Tool Design

Each tool should:
  • Have a clear, descriptive name (e.g., search_repositories, create_task)
  • Include a comprehensive description explaining what it does and when to use it
  • Define a complete JSON schema for input parameters
  • Return structured, informative results
Example: 
{
  "name": "search_repositories",
  "description": "Search GitHub repositories by keyword or topic. Use this to find repositories before performing operations like creating issues or PRs. Returns repository names, descriptions, and URLs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query (repository name, topic, or keyword)"
      },
      "limit": {
        "type": "number",
        "description": "Maximum number of results (default: 10)",
        "default": 10
      }
    },
    "required": ["query"]
  }
}
Agents use tool descriptions and server instructions together to decide when and how to call your tools. See Tool Design Philosophy for comprehensive best practices and examples.

​
Authentication

Poke supports four authentication patterns based on the MCP Authorization specification. Choose based on what you’re building:

​
No Auth

Use when: Your integration provides public data with no user identity. User experience: Works immediately after adding the URL. Zero setup required. Implementation: Your server accepts unauthenticated requests.

​
API Key

Use when: You have simple token-based authentication - good for testing or developer tools. User experience: Users paste their API key once when adding the integration. Implementation: Poke sends the key in the Authorization: Bearer <token> header on every request. Your server validates the token.
Framework support: FastMCP handles API key authentication automatically - just configure the header name if needed.

​
OAuth: Two Patterns

OAuth implementation depends on what you’re building:

​
Remote OAuth with DCR

Use when: Building a brand new service (your own data, your own users). User experience: One-time authorization, automatic token refresh. Implementation: Use an identity provider like WorkOS AuthKit to handle OAuth server. You build your tools and validate tokens. Example: A bookmark manager where users save personal bookmarks to your database.

​
OAuth Proxy

Use when: Connecting an existing API with OAuth (WHOOP, GitHub, Strava, etc.). User experience: One-time authorization, automatic token refresh. Implementation: Your MCP server acts as a bridge between Poke and the upstream OAuth provider using FastMCP’s OAuthProxy. Example: WHOOP integration - users authenticate with WHOOP, you fetch their health data.
Simple rule: Building something new? Use Remote OAuth with DCR. Connecting an existing OAuth service? Use OAuth Proxy.
What Poke handles for OAuth:
  • OAuth 2.1 + PKCE flow
  • Authorization server discovery via .well-known endpoints
  • Token storage (encrypted at rest with AES-256-GCM)
  • Automatic token refresh before expiration
See Authentication for detailed implementation guides, complete examples, and security best practices for each pattern.

​
Transport

Your MCP server exposes a single HTTPS endpoint (e.g., https://example.com/mcp). This is the URL users enter when adding your integration. Poke supports two transport protocols:
  • Streamable HTTP (default) - Latest MCP spec transport, attempted first
  • SSE (Server-Sent Events) - Automatic fallback for backward compatibility
Poke detects the working transport during initial connection and reuses it for all future calls.
Framework support: FastMCP and other modern frameworks support both transports automatically. If you’re using a framework, you don’t need to implement transport logic yourself.
Local development: Poke doesn’t support stdio transport. For local testing, use the MCP Inspector or Claude Desktop, then deploy to HTTPS for Poke integration.
See MCP Client Specification for transport implementation details.

​
Quick Reference

Here’s what you absolutely need for a working integration: Required:
  • HTTPS endpoint exposing your MCP server
  • At least one tool with clear name and description
  • Server instructions explaining when and how to use your tools
  • Authentication method (can be “No Auth” for public integrations)
Nice to have:
  • Server title for better UI display
  • Multiple tools for richer functionality
  • Well-defined JSON schemas for tool inputs
  • Detailed tool descriptions with examples
Don’t worry about:
  • Protocol version negotiation (frameworks handle this)
  • Transport layer selection (automatic)
  • Token refresh (Poke handles OAuth refresh)

​
Next Steps

Server Instructions

Start here. Learn to write instructions that make agents use your tools effectively.

Quick Start

Build your first integration with FastMCP in under 10 minutes.

Tool Design Philosophy

Best practices for creating tools agents understand.

Authentication

Choose and implement the right auth pattern.

Tool Lifecycle

Understand tool caching and updates.
Need technical specifications? See the MCP Client Specification for exact protocol versions, error codes, request/response formats, and implementation requirements.