Install the pinecone-client package and initialize the client with your API key: from pinecone import Pinecone; pc = Pinecone(api_key=YOUR_KEY).
Create an index if it does not exist: pc.create_index(name='INDEX_NAME', dimension=VECTOR_DIM, metric='cosine'), choosing the metric appropriate for your embeddings.
Connect to the index: index = pc.Index('INDEX_NAME').
Upsert vectors as a list of (id, vector, metadata) tuples: index.upsert(vectors=[('id1', [0.1, 0.2, ...], {'field': 'value'})]) in batches for large datasets.
Query the index with a vector: results = index.query(vector=QUERY_VECTOR, top_k=10, include_metadata=True) to retrieve the top-k nearest neighbors.
Parse results.matches to access each match's id, score, and metadata.
Known gotchas
Index creation is asynchronous; querying or upserting before the index status is Ready will raise an error—poll index description status before proceeding.
Vector dimensions must exactly match the index dimension; attempting to upsert a vector of a different dimension raises a dimension mismatch error.
Upserting with an existing ID overwrites the stored vector and metadata entirely; there is no partial update—send the complete vector and metadata each time.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp