MCP Server

Overview

The Grapevine MCP provides 3 categories of tools that can be used to query your Company Context: Search Tools are the core tools, intended to be used by an agent to find specific documents that match a query. These tools are intended to be used in sequence, and execute quickly. They are modeled after the tools that applications like Claude Code or Cline use to navigate a codebase. In addition to the Search Tools, we provide a pre-packaged Agent Tool that is adept at using the Search Tools to research your Company Context and answer arbitrary questions. Data Warehouse Tools allow you to query structured data warehouses like Snowflake using natural language or direct SQL for analytical queries.

Configuration

Grapevine runs as a remote MCP server at:

https://mcp.getgrapevine.ai

For more information on how to setup your Grapevine tenant, see Getting Started. For more information on how you can authenticate with the MCP, see the Authentication page.

Available tools

Search tools

These tools provide direct access to search and retrieve documents from your organization’s knowledge base.

semantic_search

Search your organization’s internal context for conceptually similar content using AI embeddings. Use this when you need to find documents that are semantically related to your query, even if they don’t contain exact keyword matches.

Request
Response

query

string

required

Natural language query to search for semantically similar content

limit

integer

default:10

Maximum number of results to return (min: 1, max: 100)

filters

SearchFilters

Filters to narrow down results. See SearchFilters for complete structure and available options

Show properties

sources

string[]

List of document sources to filter by. See Document Sources for available values

date_from

string

Start date in YYYY-MM-DD format. Only return documents created on or after this date

date_to

string

End date in YYYY-MM-DD format. Only return documents created on or before this date

provenance

string

Source-specific filter to narrow results within a connector (e.g., Slack channel name, GitHub repository name, Linear team name). See Provenance Filters for details

document_id

string

Exact document ID to retrieve. When provided, all other filters are ignored and only this specific document is returned

keyword_search

Search your organization’s internal context for documents containing specific keywords or phrases. Supports both natural language queries and advanced OpenSearch syntax.

Request
Response

query

string

required

Search query

Standard mode: Natural language keywords
Advanced mode: OpenSearch syntax with operators (AND, OR, NOT, +, -, wildcards *, field queries field:value, grouping with parentheses, fuzzy search ~, boosting ^)

limit

integer

default:10

Maximum number of results to return (min: 1, max: 100)

filters

SearchFilters

Filters to narrow down results. See SearchFilters for complete structure and available options

Show properties

sources

string[]

List of document sources to filter by. See Document Sources for available values

date_from

string

Start date in YYYY-MM-DD format. Only return documents created on or after this date

date_to

string

End date in YYYY-MM-DD format. Only return documents created on or before this date

provenance

string

Source-specific filter to narrow results within a connector (e.g., Slack channel name, GitHub repository name, Linear team name). See Provenance Filters for details

document_id

string

Exact document ID to retrieve. When provided, all other filters are ignored and only this specific document is returned

advanced

boolean

default:false

Enable advanced OpenSearch query syntax

get_document

Retrieve the full raw text content of a specific document from your organization’s internal context. Use this when you have a document ID from search results and need the complete document text.

Request
Response

document_id

string

required

Document identifier. Format varies by connector. See Document Sources and IDs for details

get_document_metadata

Retrieve metadata for a document without downloading its full text content. Use this when you only need document information like source, dates, and metadata fields.

Request
Response

document_id

string

required

Document identifier. Format varies by connector. See Document Sources and IDs for details

For complete details on document sources, ID formats, filters, and data structures, see the API Reference.

Agent Tools

ask_agent

This is the simplest way to get a comprehensive answer with citations - it is a good starting point for complex queries that require reasoning and synthesis across multiple documents.

ask_agent is akin to a Deep Research Agent - it is slow, thorough, and will answer with citations to the documents that were used to answer the question. Make sure your client is ready for large (100k+ tokens) and slow (multi-minute) responses.

Request
Response

query

string

required

User question to answer with agentic search

files

array

Optional file attachments as list of objects with:

name (string) - Filename
mimetype (string) - MIME type
content (string) - Base64 encoded file content

previous_response_id

string

Prior response ID to continue a conversation

output_format

string

Output format: use 'slack' for Slack markdown formatting

agent_prompt_override

string

Override the default system prompt

reasoning_effort

string

default:"medium"

OpenAI reasoning effort level: 'minimal', 'low', 'medium', or 'high'

verbosity

string

Response detail level: 'low', 'medium', or 'high'

disable_citations

boolean

default:false

Disable citations in the response

answer

string

The comprehensive answer with citations

response_id

string

Unique identifier for this response, can be used in previous_response_id for follow-up queries

events

array

Array of events that occurred during the agentic search process

ask_agent_fast

A faster variant of ask_agent that provides quick answers without the deep research process. Use this when you need rapid responses and don’t require extensive document synthesis.

Request
Response

query

string

required

User question to answer quickly

files

array

Optional file attachments as list of objects with:

name (string) - Filename
mimetype (string) - MIME type
content (string) - Base64 encoded file content

previous_response_id

string

Prior response ID to continue a conversation

output_format

string

Output format: use 'slack' for Slack markdown formatting

agent_prompt_override

string

Override the default system prompt

reasoning_effort

string

default:"medium"

OpenAI reasoning effort level: 'minimal', 'low', 'medium', or 'high'

verbosity

string

Response detail level: 'low', 'medium', or 'high'

disable_citations

boolean

default:false

Disable citations in the response

answer

string

The answer to the query

response_id

string

Unique identifier for this response, can be used in previous_response_id for follow-up queries

events

array

Array of events that occurred during the search process

ask_agent_streaming

Streaming variant of ask_agent that returns events as they occur. Use this when you need real-time progress updates during agentic search.

Request
Response

query

string

required

User question to answer with agentic search

files

array

Optional file attachments as list of objects with:

name (string) - Filename
mimetype (string) - MIME type
content (string) - Base64 encoded file content

previous_response_id

string

Prior response ID to continue a conversation

output_format

string

Output format: use 'slack' for Slack markdown formatting

agent_prompt_override

string

Override the default system prompt

reasoning_effort

string

default:"medium"

OpenAI reasoning effort level: 'minimal', 'low', 'medium', or 'high'

verbosity

string

Response detail level: 'low', 'medium', or 'high'

disable_citations

boolean

default:false

Disable citations in the response

answer

string

The comprehensive answer with citations

response_id

string

Unique identifier for this response, can be used in previous_response_id for follow-up queries

citations

array

Array of citations to source documents used to generate the answer

events

array

Array of streaming events as they occur during the agentic search process

Event types: status, tool_call, tool_result, final_answer, message

Data Warehouse Tools

These tools allow you to query structured data warehouses for analytical insights. They require a connected data warehouse (e.g., Snowflake) with semantic models configured.

Data warehouse tools are READ-ONLY. They cannot modify, insert, update, or delete data.

ask_data_warehouse

Query structured data warehouses using natural language. The tool translates your question into SQL using AI (e.g., Snowflake Cortex Analyst) and executes it against the data warehouse.When to use:

Get metrics, numbers, or quantitative data (revenue, counts, averages)
Perform aggregations (top 10, sum, count, group by)
Compare time periods (last quarter vs this quarter)
Filter or slice data by dimensions (by region, by product, by customer)

Difference from search tools:

ask_data_warehouse: Queries structured data tables for metrics and analytics
semantic_search/keyword_search: Searches unstructured documents (Slack, GitHub, Notion)

Request
Response

question

string

required

Natural language question to query the data warehouseExamples:

“What were our top 10 customers by revenue last quarter?”
“Show me sales by region for Q4”
“How many support tickets did we close last month?”
“What’s the average deal size for enterprise customers?”

source

string

default:"snowflake"

Data warehouse source. Currently supported: snowflake

semantic_model_id

string

Specific semantic model ID to use. If not provided, uses the tenant’s default or first available model.

limit

integer

default:100

Maximum number of rows to return (min: 1, max: 1000)

execute_data_warehouse_sql

Execute a READ-ONLY SQL query directly on a structured data warehouse. Use this when you have a specific SELECT query to run and want precise control over the query structure.

This tool is strictly READ-ONLY. The following operations are forbidden: INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, MERGE, REPLACE, GRANT, REVOKE.

Request
Response

sql

string

required

SQL SELECT query to executeExample:

SELECT customer_id, SUM(revenue) AS total_revenue
FROM orders
GROUP BY customer_id
ORDER BY total_revenue DESC
LIMIT 10

source

string

default:"snowflake"

Data warehouse source. Currently supported: snowflake

warehouse

string

Warehouse/compute cluster to use for query execution. Uses user’s default if not specified.

limit

integer

default:100

Maximum number of rows to return (min: 1, max: 1000)

Getting started

Features

Examples

Connectors

Overview

Configuration

Available tools

Search tools

Agent Tools

Data Warehouse Tools

Getting started

Features

Examples

Connectors

​Overview

​Configuration

​Available tools

​Search tools

​Agent Tools

​Data Warehouse Tools

Overview

Configuration

Available tools

Search tools

Agent Tools

Data Warehouse Tools