Back to Guides

Guide Origin: Official | ArcKit Version: [VERSION]

Pinecone is an optional vector database MCP that enables semantic search across architecture artifacts and organisational documents. Unlike the bundled MCPs (AWS Knowledge, Microsoft Learn, Google Developer Knowledge, Data Commons), Pinecone is not included in the ArcKit plugin and must be configured separately.

Optional Integration: This MCP is for advanced users who want semantic search capabilities. ArcKit works fully without it.

What Pinecone MCP Provides

Pinecone's MCP server offers 9 tools for vector database operations:

Tool Purpose
search-docs Search Pinecone documentation
list-indexes List available indexes
describe-index Get index details
describe-index-stats Get index statistics
create-index-for-model Create new indexes
upsert-records Insert/update vector records
search-records Query with metadata filtering & reranking
cascading-search Search across multiple indexes
rerank-documents Rerank results using specialised models

Wardley Book Knowledge Base

ArcKit maintains a Pinecone vector database containing Simon Wardley's complete published works on Wardley Mapping — doctrine, case studies, strategic plays, evolution analysis, and climatic patterns.

When the Pinecone MCP is configured, the /arckit:wardley command automatically searches this knowledge base to:

  • Ground component positioning in Wardley's analysis of evolution stages
  • Find relevant case studies matching the project's domain and strategic situation
  • Identify applicable gameplay patterns with examples from the books
  • Surface doctrine lessons relevant to the organisation's context

This complements the local reference files (wardley-mapping/references/) which contain curated extracts. The Pinecone index provides access to the full depth of the source material — extended reasoning, historical examples, and nuanced strategic advice.

Other Use Cases

Use Case Description
Cross-project search "Which projects have requirements related to data sovereignty?" across dozens of projects
Impact analysis "What stakeholders and risks are affected by a change to the authentication service?"
Duplicate detection Find overlapping or contradictory requirements across projects
Portfolio search "Show me all ADRs related to cloud migration decisions"
Policy alignment Check architecture decisions against existing corporate policies and standards
Knowledge discovery Surface relevant existing documentation when starting a new project

Prerequisites

  1. Pinecone account — Free tier available (limited to 1 index). Sign up at https://www.pinecone.io/
  2. Pinecone API key — Generate from the Pinecone console
  3. Node.js — Required to run the MCP server via npx

Configuration

Add to your project .mcp.json (not the plugin — configure per-project):

{
  "mcpServers": {
    "pinecone": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pinecone-database/mcp"],
      "env": {
        "PINECONE_API_KEY": "${PINECONE_API_KEY}"
      }
    }
  }
}

Set the environment variable:

export PINECONE_API_KEY="your-api-key-here"

Restart Claude Code after adding the configuration.

How It Differs from Bundled MCPs

Bundled MCPs Pinecone
Included in plugin Yes (auto-configured) No (user-configured)
Server type http (remote endpoint) stdio (local process)
Local dependencies None Node.js required
Cost Free (AWS, Microsoft Learn) or free API key (Google, Data Commons) Free tier limited; paid for production
Data Pre-loaded (documentation, public datasets) Wardley books index pre-populated; other indexes user-managed
Setup effort Zero-config or env var only Account + API key + Node.js

ArcKit Command Integration

Command How Pinecone is used
/arckit:wardley Searches Wardley book corpus for relevant strategic context, case studies, gameplay patterns, and evolution analysis to ground map creation

The wardley command detects Pinecone tools automatically and uses them when available. If not configured, it falls back to local reference files — no functionality is lost.

Working Example

The arckit-test-project-v7-nhs-appointment test repo has a working Pinecone MCP configuration that can be used as a reference.

Resources